SolarNode Receive Instructions From SolarNet

SolarNode: handling instructions from SolarNet

SolarNet has the ability to include instructions in responses it sends to the SolarIn bulk upload API. A response from that API that includes an instruction looks like this:

{
  "success" : true,
  "message" : "some message",
  "data" : {
    "datum" : [
      { "id" : "abc" ... },
      ...
    ],
    "instructions" : [
      {
        "topic" : "Mock/Topic",
        "id" : "1",
        "instructionDate" : "2014-01-01 12:00:00.000Z",
        "parameters" : [
          { "name" : "foo", "value" : "bar" }
        ]
      },
      ...
    ]
  }
}

SolarNode handles these instructions via an asynchronous process. The process works like this:

1. SolarNode sends a POST request to SolarIn
2. SolarIn responds with a success message, and includes any queued instructions.
3. SolarNode parses the instructions from the response, turns them into net.solarnetwork.node.reactor.Instruction objects with a processing state of Received, and stores them in local storage using the net.solarnetwork.node.reactor.InstructionDao API.
4. A periodic job looks for Instruction objects in local storage that need processing. For each Instruction found, it looks for a published net.solarnetwork.node.reactor.InstructionHandler service that will accept and process the Instruction.
5. If an Instruction cannot be processed (e.g. no InstructionHandler is available to process it) its processing state is changed to Declined state and updated in local storage. Otherwise the processing state is changed to Completed if successfully handled, Executing if processing will continue, or Declined if processing is rejected.

Instruction acknowledgement

At this point in the process, an instruction from SolarNet will have been handled on SolarNode, but SolarNet does not know what the outcome of the instruction is. The net.solarnetwork.node.reactor.InstructionAcknowledgementService defines an API for informing SolarNet of just that. The net.solarnetwork.node.upload.bulkjsonwebpost plug-in provides an implementation of this API. This is the same service that pushes Datum data using the SolarIn API, because that API accepts instruction status objects as well.

1. The net.solarnetwork.node.reactor.simple plug-in publishes a periodic job that queries for local Instruction objects needing to post their status to SolarNet.
2. The job uses the InstructionAcknowledgementService to post the acknowledgements to SolarNet.
3. The acknowledged state is persisted on the local Instruction.

Instruction cleanup

Another periodic job runs and deletes old acknowledged Instruction objects from local storage, so they don't accumulate forever.