About the EdgeThingTemplate
The EdgeThingTemplate is a collection ofservice implementations, property definitions, and event definitions (data shapes). It is not backed by an in-memory instance or database storage. On the edge, it is a working description of a Thing template on ThingWorx platform. The class name VirtualThing implies that this class represents a thing directly. To provide consistency in terminology with ThingWorx platform and backwards compatibility with previous versions of the Edge Java SDK, all of the ETS functionality is contained in the new class, EdgeThingTemplate, which extends VirtualThing.
The following diagram shows the structure of the EdgeThingTemplate:
As can be seen in the diagram above, an ETT also implements a ConnectedThingClientChangeListener. This interface allows the ETT to receive notifications on changes in the state of the ConnectedThingClient. This information allows changes in the state of the connection to be communicated down from the ETT to any shapes that may be part of the ETT. The ConnectedThingClient has been modified to support the Observer Pattern and can now emit any of the following events to any class extending the ETT:
TheConnectedThingClientChangeListener supports the following notifications:
public enum EventName { CLIENT_STARTED,CLIENT_SHUTDOWN,ENDPOINT_OPENED,ENDPOINT_CLOSED}
In addition to receiving events from the ConnectedThingClient, the ETT instantiates and tracks all the Edge Thing Shapes that have been declared in the annotations of the classes that extend it. For example:
package com.thingworx.sdk.edgethingshapes;
import com.thingworx.communications.client.ConnectedThingClient;
import com.thingworx.communications.client.things.EdgeThingTemplate;
import com.thingworx.communications.client.things.exceptions.InvalidAnnotationArgumentException;
import com.thingworx.metadata.annotations.ThingworxEdgeThingShapeDefinition
import com.thingworx.metadata.annotations.ThingworxEdgeThingShapeDefinitions;
@ThingworxEdgeThingShapeDefinitions(shapes = {
@ThingworxEdgeThingShapeDefinition(className =
"com.thingworx.sdk.edgethingshapes.FileEdgeShape", name = "FileEdgeShape")
})
public class MyFileEdgeTemplate extends EdgeThingTemplate {
public MyFileEdgeTemplate(String name, String description, ConnectedThingClient client)
throws InvalidAnnotationArgumentException {
super(name, description, client);
}
}
import com.thingworx.communications.client.ConnectedThingClient;
import com.thingworx.communications.client.things.EdgeThingTemplate;
import com.thingworx.communications.client.things.exceptions.InvalidAnnotationArgumentException;
import com.thingworx.metadata.annotations.ThingworxEdgeThingShapeDefinition
import com.thingworx.metadata.annotations.ThingworxEdgeThingShapeDefinitions;
@ThingworxEdgeThingShapeDefinitions(shapes = {
@ThingworxEdgeThingShapeDefinition(className =
"com.thingworx.sdk.edgethingshapes.FileEdgeShape", name = "FileEdgeShape")
})
public class MyFileEdgeTemplate extends EdgeThingTemplate {
public MyFileEdgeTemplate(String name, String description, ConnectedThingClient client)
throws InvalidAnnotationArgumentException {
super(name, description, client);
}
}
In this example, MyFileEdgeTemplate includes the FileEdgeShape. The ETT is responsible for instantiating an instance of FileEdgeShape as part of any of its constructors.
When implementing an ETT, you can choose the EdgeThingShapes that have the functionality that you want to include in the edge things that will be derived from the template. Theoretically, there is no limit to the number of these shapes that can be added to an EdgeThingTemplate. Make sure that the performance of individual service calls is not a function of the number of ETS instances that have been added to the template.
You can also choose which ETT constructors you want to support. That said, all constructors must be responsible for creating any annotated ETS. The annotation, ThingworxEdgeThingShapeDefinition supports a name attribute. This attribute is an instance name that is used to allow the same ETS to be used more than once in the ETT.
 | All ETT constructors always call the method, initializeFromAnnotations(). If no annotations are present, this method must complete without error. If initializeFromAnnotations() fails, all constructors must throw an InvalidAnnotationArgumentException at runtime to signal that a value that is present in an annotation attribute is unacceptable. |
The ETT also supports a method, getShapeInstances(), which returns a map of all instances to their identifier names. Existing VirtualThing event handlers in the ETT have been modified to use the on[EventName] naming convention to indicate to you that they are intended to override these functions to be notified of events. Existing methods are still supported. For example, you can override afterBinding or onAfterBinding() so that you are notified when your ETT instance has been bound to the ThingWorx platform.
The following UML class diagram lists the new methods that are provided in the ETT (beyond the existing ones in VirtualThing).
| | The method handleServiceRequest() in the diagram above is overridden to implement the routing of ETS service calls to the appropriate ETS class instance. In previous versions of the Edge Java SDK, this function was marked final in VirtualThing; this has also changed. |
The ETT must relay any events that it receives to each of its Edge Thing Shapes because they participate in the same lifecycle as their composing parent instance.