Implementing a Java Agent

To implement your own Agent, add the following basic code to your java application:

  • Create an instance of RemoteServer and specify Iotellect Server address/port, name of user account to use for registration and Agent's password.

    • In Iotellect Server API, the password field of RemoteServer object is used as a password for the server user account.

    However, Agent class uses password field as the password for the Agent's server-side Device account. It doesn't match the password of Agent owner's user account.

    If Agent account with the name specified in Agent class constructor already exists and passwords of Agent account and Agent application do not match, Agent won't be able to log in to the server.

  • Create an instance of Agent and specify name of Agent's Device account in the constructor.
  • Get an instance of Context using Agent.getContext() and add definitions/implementations of variables, functions, and events using addVariableDefinition(), addFunctionDefinition() and addEventDefinition() methods.
  • Call Agent.connect() to make your Agent connect to the Iotellect Server and authenticate/authorize. This call may fail for many reasons, including server unavailability, wrong server address/port, missing or disabled server-side Agent driver, incompatible Java libraries versions, missing user account, and incorrect Agent's device account password.
  • Start periodically calling Agent.run() method. It will server a single server command and return, so it should be basically called from a separate thread. At this point, your custom VariableGetter, VariableSetter and FunctionImplementation will be called. If run() method throws a DisconnectionException, server communication has failed for some reason and connection should be re-established.
  • Once Agent.getContext().isSynchronized() method will return true, your application may start generating Agent events using Agent.getContext().fireEvent() method.
  • To disconnect from the server and stop the Agent, call Agent.disconnect().

    • If some events are generated when Agent is not connected to the server or not yet synchronized, these events should be stored locally (in memory or some persistent storage) and sent to Iotellect Server upon first opportunity.

    Providing Historical Values

    Many Agents have periodic or unstable connections with Iotellect Server. Since Agents keep receiving and/or producing data during server disconnection periods, they need to send historical logs to the server once connection was re-established.

    If an Agent supports historical value reporting, it should define getHistory() function. This function will be called by the server soon after connection. The function should return a list of historical values along with their timestamps.

    An Agent should not asynchronously report any value changes (see Informing Server About Variable Updates below) until it makes sure that getHistory() has been called and the Agent itself replied with an empty table (i.e. "no more data"). Failure to do so will cause errors in Iotellect Server statistical channels.

    Informing Server About Variable Updates

    An agent can notify the server that value of a certain variable has been changed. Such notification will cause out-of-order server cache update that may occur between synchronizations.

    To send a variable update notification, use updated event (example for Java-based Agent):

    DataTable newTemperatureValue = new SimpleDataTable(agent.getContext().getVariableDefinition("temperature").getFormat(), 123.45); // Creating value table

    agent.getContext().fireEvent(AbstractContext.E_UPDATED, "temperature", newTemperatureValue);

    The updated event will-be auto-generated if you call agent.getContext().setVariable("temperature", newTemperatureValue);

    Server-Initiated Disconnections

    In certain cases (e.g. if server-side agent device account settings were changed) the server may forcibly close TCP connection with Agent. The latter should be able to detect such situation and reconnect to the server again.

    Event Confirmation

    The AgentContext class defines an eventConfirmed event that is generated each time an Iotellect Server has confirmed an Agent-generated event successful delivery and processing by calling Agent's confirmEvent() function. It's possible to add a listener for eventConfirmed event and react to event delivery confirmations, e.g. by removing delivered Agent events from Agent's internal database.

    Was this page helpful?