1. Developing Applications with Oracle Internet of Things Cloud Service
  2. Develop Analytics in IoT Cloud Service
  3. Process Data Using Analytics Processors
  4. Understand the Source Template of an Analytics Processor

Understand the Source Template of an Analytics Processor

The source template for an analytics processor contains the import statement, instance attributes, code injections, and method definitions that you need to implement the logic of an analytics processor.

The source template varies according to the type of analytics processor and the links that you associate with your analytics processor. In turn, links have analytics objects associated with them which are also included in the generated source template.

The following sections discuss the different parts of the generated source template to help you understand the code and modify it to add functionality to your analytics processor.

Package

The generated source template contains the package statement for the packages contained in the fully qualified name for the implementation class of your analytics processor. When you create your analytics processor the implementation class field contains a default value. The default value for the class name uses the generic top-level domain com, followed by the name of your IoT application, followed by the name of your analytics processor.

You can modify the fully qualified class name so that the generated code uses a package and a class name of your choice.

Imports

The import statements in your generated source template vary according to the type of analytics processor, the links, and the analytics objects used in those links.

Typically your generated source template contains import statements for the following:

  • The analytics processor super class. This varies with the type of analytics processor.

  • The Link class.

  • For streaming analytics processors: The RESTRequest class.

  • The classes corresponding to the links you selected for your analytics processor.

  • For batch analytics processors: The Tuple2 class from the Scala API, and the Arrays and Pattern classes from the Java Developer Toolkit.

  • The Inject class. This class is part of the Java Development Toolkit.

  • The classes that represent the message formats and analytics objects used in the links you specified for your analytics processor.

  • The libraries you imported. For information on how to import a library, see Import Libraries.

The following source code shows an example of the import statements for a streaming analytics processor:


import oracle.iot.analytics.StreamingAnalyticsProcessor;
import oracle.iot.analytics.Link;
import oracle.iot.analytics.RESTRequest;

import oracle.iot.analytics.DataOutput;
import org.apache.spark.streaming.api.java.JavaDStream;
import org.apache.spark.api.java.JavaRDD;

import javax.inject.Inject;

import oracle.yellow.iron.machine.data.attributes.DATAMessage;
import oracle.yellow.iron.machine.data.attributes.Data;

Analytics Objects

The generated source template contains the import statements for the analytics objects used in your links. This includes the automatically generated analytics objects for message formats.

For device message and analyzed message links, the class name for the associated analytic object corresponds to the value shown in the Classname field in the Link page. You can’t edit this field. A class name based on the message format you selected appears after you save your link.

For the remaining links, the class name for the associated analytics objects corresponds to the fully qualified name you specified in the Class Name field when you created your analytics object.

You can use analytics objects to perform the following tasks:

  • Read data from a link: When you read data from a link you get the analytics object associated with that link.

  • Write data to a link: To write data to a link, you must create an instance of the analytics object associated with that link. To instantiate an analytics object you can use the empty constructor and then use setter methods to set the value of its instance attributes. Or you can pass the values as parameters to the constructor. Analytics objects are based on Avro objects. For more information, see the Apache Avro Specification.

Links

The generated source template contains a private instance attribute for each of the links you selected when creating the analytics processor, and the corresponding code for injecting the instance of that link into the instance attribute. Both lines are commented, so you must uncomment them if you want to use that link.

For example, if you defined a link with the following characteristics:

  • Name: yi_device_stream

  • Type: Device Message

  • Message Format: urn:yellow:iron:machine:data:attributes

  • ClassName (autogenerated based on message format): oracle.yellow.iron.machine.data.attributes.DATAMessage

Then your analytics processor will contain the following lines:

		@Inject @Link("yi_device_stream")
		private JavaDStream<DATAMessage> deviceMessages;

The @Link annotation uses the name of the link to inject the correct link instance, and the type parameter for JavaDStream corresponds to the class for the message format that you selected when creating the device message link.

The Java class used for the instance attribute that represents your link, depends on the type of the link.

The following table shows the Java class used for each type of link, as well as the origin of the type parameter used for that class:

Link Type Java Class Type Parameter
Device Message JavaDStream<MessageFormatClass> The autogenerated class name based on the message format that you selected for your device message link.
Analyzed Message DataOutput<MessageFormatClass> The autogenerated class name based on the message format that you selected for your analyzed message link.
SparkSQL DataOutput<AnalyticsObjectClass> The Avro class that corresponds to the analytics object that you selected for your Spark SQL link. The corresponding import statement for this class should be one of the first import statements.
NoSQL JavaRDD<AnalyticsObjectClass> The Avro class that corresponds to the analytics object that you selected for your NoSQL link. The corresponding import statement for this class should be one of the first import statements.
Oracle Database as a Service DataOutput<AnalyticsObjectClass> The Avro class that corresponds to the analytics object that you selected for your Spark Oracle Database as a Service link. The corresponding import statement for this class should be one of the first import statements.
Oracle Storage Cloud Service DataOutput<AnalyticsObjectClass> The Avro class that corresponds to the analytics object that you selected for your Oracle Storage Cloud Service link. The corresponding import statement for this class should be one of the first import statements.

Methods to Implement

If you created a streaming analytics processor, then your source template will contain the method setup with the signature public void setup().

If you created a batch analytics processor, then your source template will contain the method execute with the signature public ReturnType execute(ParameterType param) throws Exception, where the return type and the parameter type correspond to the Java classes for the analytics objects you selected when you created the analytics processor.

The body of these methods is empty. You can implement the functionality for the method in your analytics processor code using Spark Java APIs. See the Spark Javadoc. You can also use the classes and methods from the libraries that you imported to your application. See Import Libraries.