Measurement

FRAMES NO FRAMES

Overview

Package

Deprecated

Help

API Reference for EPL (ApamaDoc) 10.5.4.1

SUMMARY: IMPORT | CONSTANT | MEMBER | ACTION

DETAIL: IMPORT | CONSTANT | MEMBER | ACTION

com.apama.cumulocity
Event Measurement

Measurement data.

Sent by the transport when a device sends a new Measurement. Requires SubscribeMeasurements or configuration property subscribeToAllMeasurements. Sent to the cumulocity.measurements channel.

Examples:

 Measurement("1001","c8y_LightMeasurement","12346081",1464359004.89,{"c8y_LightMeasurement":{"e":com.apama.cumulocity.MeasurementValue(108.1,"lux",{})}},{}) 
 Measurement("1002","c8y_DistanceMeasurement","12346082",1464359005.396,{"c8y_DistanceMeasurement":{"distance":com.apama.cumulocity.MeasurementValue(344,"mm","","","",{})}},{})

Additionally, we can also create a new Measurement for a device. To create a Measurement, send a Measurement event object to Measurement.SEND_CHANNEL.

Examples:

 send Measurement("","c8y_DistanceMeasurement","123",1464359005.396,{"distance":{"distance":MeasurementValue(3.44,"mm",{})}},{}) to Measurement.SEND_CHANNEL;

Constant summary
`string`	`CHANNEL := "cumulocity.measurements"` The channel to which `Measurement` events are sent from the transport. Deprecated: [This channel constant has been deprecated. Use SUBSCRIBE_CHANNEL instead.]
`string`	`CREATE_CHANNEL := "CumulocityIoTGenericChain"` The channel to send a measurement event to create a new measurement object in Cumulocity. Deprecated: [This channel constant has been deprecated. Use SEND_CHANNEL instead.]
`string`	`SEND_CHANNEL := "CumulocityIoTGenericChain"` The channel to send a measurement event to create a new measurement object in Cumulocity.
`string`	`SUBSCRIBE_CHANNEL := "cumulocity.measurements"` The channel to which `Measurement` events are sent from the transport.

Member summary
`string`	`id` Unique identifier for this Measurement.
`string`	`type` The type of the measurement.
`string`	`source` The unique identifier of the source of the measurement. This should correspond to a ManagedObject.
`float`	`time` The time the measurement was taken, represented as the number of seconds since the epoch (1st January 1970).
`dictionary<string, dictionary<string, com.apama.cumulocity.MeasurementValue>>`	`measurements` Measurement values mapped by fragment and series.
`dictionary<string, any>`	`params` This dictionary is available to hold any other data associated with the measurement.

Action summary
`com.apama.cumulocity.Measurement`	`static` `createFromFragments(sequence<com.apama.cumulocity.MeasurementFragment> fragments)` Create Measurement event from sequence of MeasurementFragments.
`sequence<com.apama.cumulocity.MeasurementFragment>`	`getFragments()` Fragment a measurement into a sequence of MeasurementFragments.
`com.apama.cumulocity.ResponseWrapper`	`withChannelResponse(integer reqId, dictionary<string, string> headers)` Create a Measurement in Cumulocity and receive a response event confirming the change on Measurement.SUBSCRIBE_CHANNEL.
`com.apama.cumulocity.ResponseWrapper`	`withResponse(integer reqId, dictionary<string, string> headers)` Create a Measurement in Cumulocity and receive a response event on default channel, confirming the change. Deprecated: [This API has been deprecated. Use withChannelResponse API to receive confirmation on Measurement.SUBSCRIBE_CHANNEL channel.]

Constant detail

CHANNEL

string CHANNEL := "cumulocity.measurements"

Deprecated:: [This channel constant has been deprecated. Use SUBSCRIBE_CHANNEL instead.]

The channel to which Measurement events are sent from the transport.

CREATE_CHANNEL

string CREATE_CHANNEL := "CumulocityIoTGenericChain"

Deprecated:: [This channel constant has been deprecated. Use SEND_CHANNEL instead.]

The channel to send a measurement event to create a new measurement object in Cumulocity.

SEND_CHANNEL

string SEND_CHANNEL := "CumulocityIoTGenericChain"

The channel to send a measurement event to create a new measurement object in Cumulocity.

Since:: 10.5.2.0

SUBSCRIBE_CHANNEL

string SUBSCRIBE_CHANNEL := "cumulocity.measurements"

The channel to which Measurement events are sent from the transport.

Since:: 10.5.2.0

Member detail

id

string id

Unique identifier for this Measurement.

Supply as empty if creating a new Measurement

measurements

dictionary<string, dictionary<string, com.apama.cumulocity.MeasurementValue>> measurements

Measurement values mapped by fragment and series.

Dictionary mapping from fragment name to a dictionary mapping from series name to MeasurementValue objects.

params

dictionary<string, any> params

This dictionary is available to hold any other data associated with the measurement.

source

string source

The unique identifier of the source of the measurement. This should correspond to a ManagedObject.

time

float time

The time the measurement was taken, represented as the number of seconds since the epoch (1st January 1970).

type

string type

The type of the measurement.

Action detail

createFromFragments

com.apama.cumulocity.Measurement static createFromFragments(sequence<com.apama.cumulocity.MeasurementFragment> fragments)

Create Measurement event from sequence of MeasurementFragments.

All the MeasurementFragment objects in sequence should have same id, type, source and time. Else a CorruptFragmentSeriesException exception is thrown.

Parameters:: fragments

getFragments

sequence<com.apama.cumulocity.MeasurementFragment> getFragments()

Fragment a measurement into a sequence of MeasurementFragments.

The sequence size is same as the number of Fragments present in the Measurement. A Measurement with no Fragment will fetch an empty sequence.

withChannelResponse

com.apama.cumulocity.ResponseWrapper withChannelResponse(integer reqId, dictionary<string, string> headers)

Create a Measurement in Cumulocity and receive a response event confirming the change on Measurement.SUBSCRIBE_CHANNEL.

Just sending a Measurement is fire and forget. If your application requires an acknowledgement or the ID of the Measurement created on Measurement.SUBSCRIBE_CHANNEL channel, then use the withChannelResponse API. You will need to subscribe to Measurement.SUBSCRIBE_CHANNEL channel. This API will create an event that can be sent as normal and get a response from Cumulocity for the newly created Measurement. The responses are either an ObjectCommitted event or an ObjectCommitFailed event. The withChannelResponse API also allows you to provide headers to the create or update request. For example:

Measurement m := new Measurement;
monitor.subscribe(Measurement.SUBSCRIBE_CHANNEL);
// set fields in m
integer reqId := com.apama.cumulocity.Util.generateReqId();
send m.withChannelResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Measurement.SEND_CHANNEL;
on ObjectCommitted(reqId=reqId) as commit and not ObjectCommitFailed(reqId=reqId) {
    // do something
}
on ObjectCommitFailed(reqId=reqId) as failure and not ObjectCommitted(reqId=reqId) {
    // do something
}

Parameters:: reqId - A request identifier generated from Util.generateReqId(). The response from Cumulocity will have the matching request identifier.; headers - Set headers of the create request. This can be used to explicitly control the processing mode of the create request.

See Also:: com.apama.cumulocity.ObjectCommitted - Successfully created a Measurement.; com.apama.cumulocity.ObjectCommitFailed - Failed to create a Measurement.

withResponse

com.apama.cumulocity.ResponseWrapper withResponse(integer reqId, dictionary<string, string> headers)

Deprecated:: [This API has been deprecated. Use withChannelResponse API to receive confirmation on Measurement.SUBSCRIBE_CHANNEL channel.]

Create a Measurement in Cumulocity and receive a response event on default channel, confirming the change.

Just sending a Measurement is fire and forget. If your application requires an acknowledgement or the ID of the Measurement created, then use the withResponse API. This API will create an event that can be sent as normal and get a response from Cumulocity for the newly created Measurement. The responses are sent to default channel and hence can be listened for only in the main context. The responses are either an ObjectCommitted event or an ObjectCommitFailed event. The withResponse API also allows you to provide headers to the create or update request. For example:

Measurement m := new Measurement;
// set fields in m
integer reqId := com.apama.cumulocity.Util.generateReqId();
send m.withResponse(reqId, { "X-Cumulocity-Processing-Mode": "TRANSIENT" }) to Measurement.SEND_CHANNEL;
on ObjectCommitted(reqId=reqId) as commit and not ObjectCommitFailed(reqId=reqId) {
    // do something
}
on ObjectCommitFailed(reqId=reqId) as failure and not ObjectCommitted(reqId=reqId) {
    // do something
}

Parameters:: reqId - A request identifier generated from Util.generateReqId(). The response from Cumulocity will have the matching request identifier.; headers - Set headers of the create request. This can be used to explicitly control the processing mode of the create request.

See Also:: com.apama.cumulocity.ObjectCommitted - Successfully created a Measurement.; com.apama.cumulocity.ObjectCommitFailed - Failed to create a Measurement.; com.apama.cumulocity.Measurement#withChannelResponse() - to receive confirmation on Measurement.SUBSCRIBE_CHANNEL channel.