Managing Triggers

Once triggers are registered, you can use the following features to manage them.

In any case, you need to get api, a ThingIFAPI instance, that is initialized by the steps described in Initialize Thing-IF SDK prior to executing the features.

Deleting a Trigger

The following is a sample code for deleting a trigger.

String triggerID = trigger.getTriggerID();
try {
  // Delete a trigger.
  api.deleteTrigger(triggerID);
} catch (ThingIFException e) {
  // Handle the error.
}

You need to have a triggerID to delete the trigger. You can get the triggerID with the getTriggerID method.

You can get trigger, a Trigger instance, when you register a trigger or when you get a list of triggers.

Enabling and Disabling a Trigger

You can enable or disable a trigger that is registered on the server. The disabled trigger will not be executed even if its condition is met.

The following sample code shows how to disable a trigger.

String triggerID = trigger.getTriggerID();
boolean enabled = false;
try {
  // Disable a trigger.
  api.enableTrigger(triggerID, enabled);
} catch (ThingIFException e) {
  // Handle the error.
}

In this example, we are disabling the trigger by setting the enabled to false. If you want to enable the trigger, please set the enabled to true instead.

You need to have the triggerID to enable/disable the trigger. You can get the triggerID with the getTriggerID method.

You can get trigger, a Trigger instance, when you register a trigger or when you get a list of triggers.

Updating a Trigger

You can update a registered trigger with a new process to execute, execution condition, and so on.

The following sample code shows how to update the trigger registered in the example in Registering Advanced Triggers.

The original trigger turns on the air conditioner when the thermometer device goes over 30 degrees Celsius. This sample code updates the execution condition to "when the thermometer device goes over 28 degrees Celsius" and the trigger description correspondingly.

// Get a trigger to update.
Trigger triggerOrg;
// triggerOrg = ...

// Create a command form from the existing trigger.
TriggeredCommandForm.Builder cb = TriggeredCommandForm.Builder.newBuilderFromCommand(triggerOrg.getCommand());
TriggeredCommandForm form = cb.build();

// Create a new predicate.
Condition condition = new Condition(Range.greaterThanEquals("currentTemperature", 28));
StatePredicate predicate = new StatePredicate(condition, TriggersWhen.CONDITION_FALSE_TO_TRUE);

// Create new trigger options from the existing title and metadata and a new description.
TriggerOptions.Builder ob = TriggerOptions.Builder.newBuilder();
ob.setTitle(triggerOrg.getTitle());
ob.setMetadata(triggerOrg.getMetadata());
ob.setDescription("Power on when the temperature goes over 28 deg C");
TriggerOptions options = ob.build();

try {
  // Patch the existing trigger.
  String triggerID = triggerOrg.getTriggerID();
  Trigger updatedTrigger = api.patchTrigger(triggerID, form, predicate, options);
} catch (ThingIFException e) {
  // Handle the error.
}

The general process of updating a trigger consists of the following three steps: getting the trigger to update, separately updating the trigger components, TriggeredCommandForm (command) or ServerCode (server code), StatePredicate (execution condition), and TriggerOptions (trigger details), and calling patchTrigger with those components as arguments. New trigger components such as a new command and trigger details are created by copying the original trigger definition and overwriting the parts which need update.

The following processes are executed in the code:

  • Get the trigger to update in triggerOrg. You can get a Trigger instance when you register it or when you get a list of triggers.

  • Create a new command for the updated trigger from the command in triggerOrg with the TriggeredCommandForm.Builder. Though this sample code passes the original command to patchTrigger without any changes, if you need to change any parts of the command, specify new values in the fields and create a TriggeredCommandForm with the build method. See Registering Advanced Triggers to learn how to specify the command definition.

    If you need to update a trigger which executes server code, create new endpoint information as a ServerCode. See Server Code Triggers to learn how to specify the endpoint information.

  • Create a new execution condition as a StatePredicate. See Trigger Execution Conditions to learn how to specify the execution condition.

  • Create trigger details for the updated trigger from the trigger details in triggerOrg with the TriggerOptions.Builder. Set the original title and metadata with the setTitle method and setMetadata method and set a new trigger description with the setDescription method. Then, create a TriggerOptions with the build method. See Registering Advanced Triggers to learn how to specify the trigger details.

  • Update the trigger registered with api, a ThingIFAPI instance which represents the thermometer device, by calling the patchTrigger method with the triggerID and created TriggeredCommandForm, StatePredicate, and TriggerOptions specified.

  • When the method successfully completes, the updated trigger will be stored in updatedTrigger.

You can update the trigger definition with the patchTrigger method by specifying either or both of a TriggeredCommandForm and StatePredicate. If you set a null value in any element, the null element will not be updated. For example, you will get the same result if you set a null value in the TriggeredCommandForm in the above sample code. Each field of the TriggerOptions will be updated only when a new value is specified. Otherwise, the field remains unchanged.

If you set a null value in the targetID of the TriggeredCommandForm, the thing with which you register the trigger will be set as the thing that executes the command. Pay attention if the original trigger has been registered with a different thing (thermometer device) than the thing (air conditioner) which executes the command as in the above example.

Getting a Trigger

You can get an existing trigger.

The following sample code shows how to get a trigger.

String triggerID = "_trigger_id_";

try {
  // Get a trigger.
  Trigger trigger = api.getTrigger(triggerID);
} catch (ThingIFException e) {
  // Handle the error.
}

When the method successfully completes, the obtained trigger is stored in trigger.

You need to have a triggerID to get a trigger. You can get the triggerID with the getTriggerID method.

You can get trigger, a Trigger instance, also when you register a trigger or when you get a list of triggers.

Getting a List of Triggers

You can get a list of all triggers that are registered on the server.

If there are many registered triggers, you can use the pagination. If there are 30 registered triggers, for example, you can get ten triggers per page. In this case, you can get all triggers by parsing three pages, ten triggers at a time.

The following is the sample code.

try {
  String paginationKey = null;

  do {
    // Get a list of triggers.
    Pair<List<Trigger>, String> results = api.listTriggers(0, paginationKey);
    List<Trigger> triggers = results.first;

    // Do something with each trigger.
    for (Trigger trigger : triggers) {
      Command triggerCommand = trigger.getCommand();
      StatePredicate triggerPredicate = (StatePredicate)trigger.getPredicate();
    }

    // Get the next pagination key.
    paginationKey = results.second;
  } while (paginationKey != null);
} catch (ThingIFException e) {
  // Handle the error.
}

As shown in the sample code, you can get a list of triggers with the listTriggers method.

The paginationKey represents the current page status. When you execute the listTriggers method with a null value, the first page is returned with the next pagination key being set in the second. You can get the next page by setting this value as the pagination key of the next listTriggers execution. When all triggers are obtained, a null value will be returned as the pagination key.

The first argument of the listTriggers denotes the number of triggers to get (i.e., the size of a page). If you set the number to 0 or below, the server will apply the optimal setting. The size of the page set here will be handled in a best-effort manner, so the actual number of triggers obtained can be smaller than the specified number. The triggers that could not be retrieved can be obtained on the next page.

The list of triggers is stored in the results.first. You can get the command and the conditions in the trigger.