services.json

The services.json file resides in a service's root directory and describes how the service is constructed and operates.

Schema 

{
   "description"     : string,
   "engine"          : string,   
   "commandTimeout"  : number,
   "activityTimeout" : number,
   "globalized"      : boolean,
   "services":
   [
      {
         "name"           : string,
         "description"    : string,
         "assistant"      : string,
         "commandTimeout" : number,
         "commands":
         [
            {
               "name"           : string,
               "description"    : string,
               "assistant"      : string,
               "public"         : boolean,
               "watch"          : boolean,
               "subscribe"      : boolean,
               "argsSchema"     : string | object,
               "commandTimeout" : number
             }
          ]
      }
   ],
   "schemas":
   {
      schema: object
   }
}

Properties

Property Required Type Description
description No string Used to provide an informative aaplication description.
engine No string node | triton
Selects the JavaScript engine the service runs under. Default is node.
commandTimeout No string Number of seconds commands should run before a timeout error is returned to the caller. This can be overridden (see below). If not defined, this defaults to 30 seconds.
activityTimeout No string Number of seconds the application continues to run after the completion of the last activity, before it terminates. Services do not run all the time, but launch when needed, and terminate when not in use. Typically, a command is considered to be an activity, so the application will not terminate while a command is being processed. It is also possible to have other non-command activities (e.g., background activities). If not defined, this defaults to 30 seconds.
globalized No boolean If true, locale-dependent processing, such as the way names, addresses and phone numbers are parsed, is invoked. In general, services should try to be locale-agnostic as invoking this can add significant processing time.
services Yes object array

Services the application provides. Typically, an application provides only one service. However, there may be reasons to provide multiple services within the same application (e.g., old API versions). An application must define at least one service (since an application without services probably does not make sense).

Note: more than one service per application is NOT currently supported.
name Yes string

Name of service on webOS message bus.

The name must begin with the app name. For example: 

app name: "com.palmdts.testacct" 
service name: "com.palmdts.testacct.contacts.service"
description No string Service description.
assistant No string

Name of class that should be instantiated to manage this service. The service assistant runs only once when the service starts. However, it can be used to store more-persistent state since command assistants are only around when processing a request.

For example: 

var assistant = this.controller.service.assistant;
assistant.saveState(someState);
commandTimeout No string Number of seconds commands should run before a timeout error is returned to the caller. This overrides any value defined at the application level for this service, but may be overridden in turn by a command (see below). If not defined, this inherits the value defined for the application.
commands Yes object array Commands this service provides. A service may provide zero or more commands per service (a service with no commands may simply want to run once when the application is started).
name Yes string Command name.
description No string Command description
assistant Yes string Name of class that should be instantiated to manage this command. The command assistant's run method is called to execute the command.
public No boolean If true, the command is callable on the public bus.
watch No boolean

If true, this command is watchable. A watchable command has two return values to the caller:

  1. The first return value is the usual response to the command.

  2. The second return value, which is sent sometime later, indicates that the command should be re-executed, because the value it returns may be different from the last time it was called.

This mechanism is similar to subscriptions, but is naturally rate-limited by the consumer of the service, resulting in less unnecessary bus traffic and fewer application stampedes when service state changes.

Defaults to false if not present.
subscribe No boolean

If true, this command supports subscriptions. To subscribe, an app or service sets subscribe=true in the request.

A subscription is typically used for a command which can take a long time to run, but where incremental progress can be indicated to the caller. The webOS Download Manager is an example of a service that implements subscriptions.

Commands which have a subscription active do not time out.

For a subscribeable command, the run() function is passed a second parameter, which is a FutureFactory object, which provides Future objects for subsequent responses.

Example: 

run: function(future, subscription) {
    var count = 1;
    future.result = { reply: "this is the initial response"};
    this.interval = setInterval(function ping() {
       // subscription.get() returns a future to use for the next response
       var f = subscription.get();
       f.result = { reply: "response #"+count++};
    }, 1000);
},

Apps implementing a subscribable command should make requests from the application with Mojo.Service.Request, rather than using the Mojo.Controller.SceneController's request() method, since the controller cancels any requests when the scene closes.

Defaults to false if not present.
argsSchema No string | object Defines a JSON schema used to validate incoming command arguments. This can either be a JSON schema or a string. If a string is used, this should match a property in the application-level schema object.
commandTimeout No number Number of seconds this command should run before a timeout error is returned to the caller. This overrides any value defined at the service or application level. If not defined, this inherits the value defined by the service or the application.
schemas No object Command arguments may be optionally validated using a JSON Schema. If a schema is used, the service executes only validated commands. Otherwise, schema errors are returned to the caller.
schema No object The schema property at the application level defines a set of string/schema pairs. Each named schema can be referenced by zero or more commands using their schema property. The value of the pair corresponds to a JSON schema, which is used for command validation.


Example 

{
   "id":"com.palmdts.testacct.contacts.service",
   "description":"Test Contact Service",
   "engine":"node",
   "activityTimeout":60,
   "services":[
      {
         "name":"com.palmdts.testacct.contacts.service",
         "description":"Test Contact",
         "globalized":false,
         "commands":[
            {
               "name":"checkCredentials",
               "assistant":"checkCredentialsAssistant",
               "public":true
            },
            {
               "name":"onCapabiltiesChanged",
               "assistant":"onCapabiltiesChangedAssistant",
               "public":true
            },  
            {
               "name":"onCredentialsChanged",
               "assistant":"onCredentialsChangedAssistant",
               "public":true
            },    
            {
               "name":"onCreate",
               "assistant":"onCreateAssistant",
               "public":true
            },    
            {
               "name":"onEnabled",
               "assistant":"onEnabledAssistant",
               "public":true
            },        
            {
               "name":"onDelete",
               "assistant":"onDeleteAssistant",
               "public":true
            },            
            {
               "name":"sync",
               "assistant":"syncAssistant",
               "public":true
            }                                                                    
         ]
      }
   ]
}

Security

The LS2 security role files will be automatically created from services.json at build time. You will be able to override certain default behavior with custom properties in the services.json file. Check back soon for details.