IotProvider (Apache Edgent (Java 8): Providers: IoT 1.2.0 API)

java.lang.Object
- org.apache.edgent.providers.iot.IotProvider

All Implemented Interfaces:

org.apache.edgent.execution.DirectSubmitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job>, org.apache.edgent.execution.Submitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job>, org.apache.edgent.topology.TopologyProvider
```
public class IotProvider
extends Object
implements org.apache.edgent.topology.TopologyProvider, org.apache.edgent.execution.DirectSubmitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job>
```
A provider that supports sharing of a single connection to an IoT message hub and access to control MBeans via IoT device commands.
```
 // sample use
 class MyApp {
   ...
   public void run(String[] args) throws Exception {
      IotProvider provider = new IotProvider((top) -> new IotpDevice(top, myDeviceConfig));
      provider.registerTopology("app1", (iotDevice, cfg) -> buildApp1(iotDevice, cfg));
      provider.start();
   }
   private void buildApp1(IotDevice iotDevice, JsonConfig cfg) {
      Topology top = iotDevice.getTopology();
      ... build the topology
   }
 }
 
```
The registered builders are subsequently invoked from ApplicationServiceMXBean.submit(). Each builder invocation is given a virtual IotDevice for the topology's use. Jobs can be stopped using their JobMXBean control.
Applications may also be registered via registerJar(). See the note below regarding the TopologyBuilder for such applications.
Constructed topologies may also be submitted via submit() and are controllable via their JobMXBean. The ApplicationService is unaware of these topologies.
See the package documentation for details of using edgentControl IoT device commands to invoke methods on MBeans registered with the ControlService.
This provider registers these services:
- control - An instance of JsonControlService.
- application - An instance of AppService.
- publish-subscribe - An instance of ProviderPubSub
- preferences (optional) - An instance of java.util.prefs.Preferences to store application and service preferences. A Preferences node is created if the provider is created with a name that is not null. If the preferences implementation supports persistence then any preferences will be maintained across provider and JVM restarts when creating a provider with the same name. The Preferences node is a user node.
System applications provide:
- Single connection to the message hub using an IotDevice using IotDevicePubSub. Applications using this provider that want to connect to the message hub for device events and commands must create an instance of IotDevice using addIotDevice(). See below for more information.
- Access to the control service through device commands from the message hub.
If topology builders are registered with the ApplicationService using something other than this provider's registerTopology(), that code is responsible for creating the virtual IotDevice as described above on each builder invocation.
For example, an application loaded and registered via ApplicationService.registerJar() would create the IotDevice for its builder in its TopologyBuilder.getBuilder() implementation:
```
 class MyApp implements TopologyBuilder {  // be loadable by registerJar()
   @Override
   public BiConsumer<Topology t, JsonConfig c> getBuilder() {
     return (t, c) -> buildTopology(IotDevicePubSub.addIotDevice(t), c);
   }
   private void buildTopology(IotDevice iotDevice, JsonConfig c) {
     Topology t = iotDevice.getTopology();
     ... build your topology
   }
 }
 
```
See Also:

IotDevice, IotDevicePubSub

Field Summary

Fields
Modifier and Type Field and Description

static String CONTROL_APP_NAME
IoT control using device commands application name.

Fields
Modifier and Type	Field and Description
`static String`	`CONTROL_APP_NAME` IoT control using device commands application name.

Constructor Summary

Constructors
Constructor and Description
`IotProvider(org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)` Create an `IotProvider` that uses its own `DirectProvider`.
`IotProvider(String name, DirectProvider provider, org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)` Create an `IotProvider` that uses the passed in `DirectProvider`.
`IotProvider(String name, org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)` Create an `IotProvider` that uses its own `DirectProvider`.
`IotProvider(String name, org.apache.edgent.topology.TopologyProvider provider, org.apache.edgent.execution.DirectSubmitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job> submitter, org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)` Create an `IotProvider`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`createIotCommandToControlApp()` Create application connects `edgentControl` device commands to the control service.
`protected void`	`createIotDeviceApp()` Create application that connects to the message hub.
`protected void`	`createJobMonitorApp()` Create Job monitor application.
`protected IotDevice`	`createMessageHubDevice(org.apache.edgent.topology.Topology topology)` Create the connection to the message hub.
`org.apache.edgent.topology.services.ApplicationService`	`getApplicationService()` Get the application service.
`protected JsonControlService`	`getControlService()`
`String`	`getName()` Return the name of this provider.
`static Preferences`	`getPreferences(String providerName)` Get the Preferences node that will be used for the IotProvider with the specified name.
`org.apache.edgent.execution.services.ServiceContainer`	`getServices()`
`org.apache.edgent.topology.Topology`	`newTopology()`
`org.apache.edgent.topology.Topology`	`newTopology(String name)`
`protected void`	`registerApplicationService()`
`protected void`	`registerControlService()`
`protected void`	`registerPreferencesService()`
`protected void`	`registerPublishSubscribeService()`
`void`	`registerTopology(String applicationName, org.apache.edgent.function.BiConsumer<IotDevice,com.google.gson.JsonObject> builder)` Register an application that uses an `IotDevice`.
`void`	`registerTopology(String applicationName, org.apache.edgent.function.BiConsumer<IotDevice,com.google.gson.JsonObject> builder, boolean autoSubmit, com.google.gson.JsonObject config)` Register an application that uses an `IotDevice`.
`void`	`start()` Start this provider by starting its system applications and any autoSubmit-enabled registered applications.
`Future<org.apache.edgent.execution.Job>`	`submit(org.apache.edgent.topology.Topology topology)`
`Future<org.apache.edgent.execution.Job>`	`submit(org.apache.edgent.topology.Topology topology, com.google.gson.JsonObject config)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - CONTROL_APP_NAME
```
public static final String CONTROL_APP_NAME
```
    IoT control using device commands application name.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - IotProvider
```
public IotProvider(org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)
```
    Create an IotProvider that uses its own DirectProvider. No name is assigned to the provider so a preferences service is not created.
    
    Parameters:
    
    iotDeviceCreator - How the IotDevice is created.
    
    See Also:
    
    DirectProvider
  - IotProvider
```
public IotProvider(String name,
                   org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)
```
    Create an IotProvider that uses its own DirectProvider.
    
    Parameters:
    
    name - Name of the provider, if the value is not null then a preferences service is created.
    
    iotDeviceCreator - How the IotDevice is created.
    
    See Also:
    
    DirectProvider
  - IotProvider
```
public IotProvider(String name,
                   DirectProvider provider,
                   org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)
```
    Create an IotProvider that uses the passed in DirectProvider.
    
    Parameters:
    
    name - Name of the provider, if the value is not null then a preferences service is created.
    
    provider - DirectProvider to use for topology creation and submission.
    
    iotDeviceCreator - How the IotDevice is created.
    
    See Also:
    
    DirectProvider
  - IotProvider
```
public IotProvider(String name,
                   org.apache.edgent.topology.TopologyProvider provider,
                   org.apache.edgent.execution.DirectSubmitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job> submitter,
                   org.apache.edgent.function.Function<org.apache.edgent.topology.Topology,IotDevice> iotDeviceCreator)
```
    Create an IotProvider.
    
    Parameters:
    
    name - Name of the provider, if the value is not null then a preferences service is created.
    
    provider - How topologies are created.
    
    submitter - How topologies will be submitted.
    
    iotDeviceCreator - How the IotDevice is created.
- Method Detail
  - getName
```
public String getName()
```
    Return the name of this provider.
    
    Returns:
    
    Provider's name, can be null.
  - getApplicationService
```
public org.apache.edgent.topology.services.ApplicationService getApplicationService()
```
    Get the application service. Callers may use this to register applications to be executed by this provider.
    
    Returns:
    
    application service.
  - getServices
```
public org.apache.edgent.execution.services.ServiceContainer getServices()
```
    Specified by:
    
    getServices in interface org.apache.edgent.execution.DirectSubmitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job>
  - newTopology
```
public final org.apache.edgent.topology.Topology newTopology()
```
    Specified by:
    
    newTopology in interface org.apache.edgent.topology.TopologyProvider
  - newTopology
```
public final org.apache.edgent.topology.Topology newTopology(String name)
```
    Specified by:
    
    newTopology in interface org.apache.edgent.topology.TopologyProvider
  - submit
```
public final Future<org.apache.edgent.execution.Job> submit(org.apache.edgent.topology.Topology topology)
```
    Specified by:
    
    submit in interface org.apache.edgent.execution.Submitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job>
  - submit
```
public final Future<org.apache.edgent.execution.Job> submit(org.apache.edgent.topology.Topology topology,
                                                            com.google.gson.JsonObject config)
```
    Specified by:
    
    submit in interface org.apache.edgent.execution.Submitter<org.apache.edgent.topology.Topology,org.apache.edgent.execution.Job>
  - registerControlService
```
protected void registerControlService()
```
  - registerApplicationService
```
protected void registerApplicationService()
```
  - registerPublishSubscribeService
```
protected void registerPublishSubscribeService()
```
  - registerPreferencesService
```
protected void registerPreferencesService()
```
  - getPreferences
```
public static Preferences getPreferences(String providerName)
```
    Get the Preferences node that will be used for the IotProvider with the specified name.
    
    Parameters:
    
    providerName - The value that will be passed into IotProvider()
    
    Returns:
    
    Preferences
  - getControlService
```
protected JsonControlService getControlService()
```
  - createIotDeviceApp
```
protected void createIotDeviceApp()
```
    Create application that connects to the message hub. Subscribes to device events and sends them to the messages hub. Publishes device commands from the message hub.
    
    See Also:
    
    IotDevicePubSub, createMessageHubDevice(Topology)
  - createJobMonitorApp
```
protected void createJobMonitorApp()
```
    Create Job monitor application.
    
    See Also:
    
    JobMonitorApp
  - createIotCommandToControlApp
```
protected void createIotCommandToControlApp()
```
    Create application connects edgentControl device commands to the control service. Subscribes to device commands of type Commands.CONTROL_SERVICE and sends the payload into the JSON control service to invoke the control operation.
  - start
```
public void start()
           throws Exception
```
    Start this provider by starting its system applications and any autoSubmit-enabled registered applications.
    
    Throws:
    
    Exception - on failure starting applications.
  - createMessageHubDevice
```
protected IotDevice createMessageHubDevice(org.apache.edgent.topology.Topology topology)
```
    Create the connection to the message hub. Creates an instance of IotDevice used to communicate with the message hub. This provider creates and submits an application that subscribes to published events to send as device events and publishes device commands.
    The application is created using IotDevicePubSub.createApplication(IotDevice).
    The IotDevice is created using the function passed into the constructor.
    
    Parameters:
    
    topology - Topology the IotDevice will be contained in.
    
    Returns:
    
    IotDevice device used to communicate with the message hub.
    
    See Also:
    
    IotDevice, IotDevicePubSub
  - registerTopology
```
public void registerTopology(String applicationName,
                             org.apache.edgent.function.BiConsumer<IotDevice,com.google.gson.JsonObject> builder)
```
    Register an application that uses an IotDevice.
    Same as registerTopology(appName, builder, false, null).
    
    Parameters:
    
    applicationName - Application name
    
    builder - Function that builds the topology.
  - registerTopology
```
public void registerTopology(String applicationName,
                             org.apache.edgent.function.BiConsumer<IotDevice,com.google.gson.JsonObject> builder,
                             boolean autoSubmit,
                             com.google.gson.JsonObject config)
```
    Register an application that uses an IotDevice.
    Wrapper around ApplicationService.registerTopology(String, BiConsumer) that passes in an IotDevice and configuration to the supplied function builder that builds the application. The passed in IotDevice is created using IotDevicePubSub.addIotDevice(org.apache.edgent.topology.TopologyElement).
    Note that builder obtains a reference to its topology using TopologyElement.topology().
    When the application is submitted builder.accept(iotDevice, config) is called to build the application's graph.
    
    Specify autoSubmit==true, to have the provider submit the application when start() is called.
    
    Parameters:
    
    applicationName - Application name
    
    builder - Function that builds the topology.
    
    autoSubmit - auto submit the application when start() is called.
    
    config - config for auto-submitted application. See submit. May be null.

Class IotProvider

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CONTROL_APP_NAME

Constructor Detail

IotProvider

IotProvider

IotProvider

IotProvider

Method Detail

getName

getApplicationService

getServices

newTopology

newTopology

submit

submit

registerControlService

registerApplicationService

registerPublishSubscribeService

registerPreferencesService

getPreferences

getControlService

createIotDeviceApp

createJobMonitorApp

createIotCommandToControlApp

start

createMessageHubDevice

registerTopology

registerTopology