ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2025-04-13 22:23:13 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #1583 from nasa/time-defaults

Browse Source 
Time defaults
This commit is contained in:
Pete Richards 2017-05-16 17:32:04 -07:00 committed by GitHub
commit fff75d111e
9 changed files with 188 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
API.md
View File

@ -547,29 +547,24 @@ numbers in UTC terrestrial time.
#### Getting and Setting the Active Time System
Once registered, a time system can be activated using a key, or an instance of
the time system itself.
Once registered, a time system can be activated by calling `timeSystem` with
the timeSystem `key` or an instance of the time system. If you are not using a
[clock](#clocks), you must also specify valid [bounds](#time-bounds) for the
timeSystem.
```javascript
openmct.time.timeSystem('utc');
openmct.time.timeSystem('utc', bounds);
```
A time system can be immediately activated upon registration:
A time system can be immediately activated after registration:
```javascript
var utcTimeSystem = {
key: 'utc',
name: 'UTC Time',
cssClass = 'icon-clock',
timeFormat = 'utc',
durationFormat = 'duration',
isUTCBased = true
};
openmct.time.addTimeSystem(utcTimeSystem);
openmct.time.timeSystem(utcTimeSystem);
openmct.time.timeSystem(utcTimeSystem, bounds);
```
Setting the active time system will trigger a [time system event](#time-events).
Setting the active time system will trigger a [`'timeSystem'`](#time-events)
event. If you supplied bounds, a [`'bounds'`](#time-events) event will be triggered afterwards with your newly supplied bounds.
### Time Bounds
@ -592,8 +587,8 @@ let now = Date.now();
openmct.time.bounds({start: now - ONE_HOUR, now);
```
To respond to bounds change events, simply register a callback against the `bounds`
event. For more information on the bounds event, please see the section on [Time Events](#time-events).
To respond to bounds change events, listen for the [`'bounds'`](#time-events)
event.
## Clocks
@ -673,14 +668,16 @@ An example clock implementation is provided in the form of the [LocalClock](http
Once registered a clock can be activated by calling the `clock` function on the
Time API passing in the key or instance of a registered clock. Only one clock
may be active at once, so activating a clock will deactivate any currently
active clock. Setting the clock will also trigger a ['clock' event](#time-events).
active clock. [`clockOffsets`](#clock-offsets) must be specified when changing a clock.
Setting the clock triggers a [`'clock'`](#time-events) event, followed by a [`'clockOffsets'`](#time-events) event, and then a [`'bounds'`](#time-events) event as the offsets are applied to the clock's currentValue().
```
openmct.time.clock(someClock);
openmct.time.clock(someClock, clockOffsets);
```
Upon being activated, a clock's `on` function will be immediately called to subscribe
to `tick` events.
Upon being activated, the time API will listen for tick events on the clock by calling `clock.on`.
The currently active clock (if any) can be retrieved by calling the same
function without any arguments.
@ -707,7 +704,7 @@ relative time spans. Offsets are defined as an object with two properties:
* `start`: A `number` that must be < 0 and which is used to calculate the start
bounds on each clock tick. The start offset will be calculated relative to the
value provided by a clock's tick callback, or its `currentValue()` function.
* `end`: A `number` that must be >=0 and which is used to calculate the end
* `end`: A `number` that must be >= 0 and which is used to calculate the end
bounds on each clock tick.
The `clockOffsets` function can be used to get or set clock offsets. For example,
@ -728,16 +725,9 @@ Clock offsets are only relevant when a clock source is active.
## Time Events
The time API supports the registration of listeners that will be invoked when the
application's temporal state changes. Events listeners can be registered using
the `on` function. They can be deregistered using the `off` function. The arguments
accepted by the `on` and `off` functions are:
The Time API is a standard event emitter; you can register callbacks for events using the `on` method and remove callbacks for events with the `off` method.
* `event`: A `string` naming the event to subscribe to. Event names correspond to
the property of the Time API you're interested in. A [full list of time events](#list-of-time-events)
is provided later.
As an example, the code to listen to bounds change events looks like:
For example:
``` javascript
openmct.time.on('bounds', function callback (newBounds, tick) {
@ -747,40 +737,38 @@ openmct.time.on('bounds', function callback (newBounds, tick) {
#### List of Time Events
The events supported by the Time API are:
The events emitted by the Time API are:
* `bounds`: Listen for changes to current bounds. The callback will be invoked
with two arguments:
* `bounds`: A [bounds](#getting-and-setting-bounds) bounds object representing
a new time period bound by the specified start and send times.
* `tick`: A `boolean` indicating whether or not this bounds change is due to a
"tick" from a [clock source](#clocks). This information can be useful when
determining a strategy for fetching telemetry data in response to a bounds
change event. For example, if the bounds change was automatic, and is due
to a tick then it's unlikely that you would need to perform a historical
data query. It should be sufficient to just show any new telemetry received
via subscription since the last tick, and optionally to discard any older
data that now falls outside of the currently set bounds. If `tick` is false,
then the bounds change was not due to an automatic tick, and a query for
historical data may be necessary, depending on your data caching strategy,
and how significantly the start bound has changed.
* `timeSystem`: Listen for changes to the active [time system](#defining-and-registering-time-systems).
The callback will be invoked with a single argument - the newly active time system.
* `timeSystem`: The newly active [time system](#defining-and-registering-time-systems) object.
* `clock`: Listen for changes to the active clock. When invoked, the callback
will be provided with the new clock.
* `clock`: The newly active [clock](#clocks), or `undefined` if an active clock
has been deactivated.
* `clockOffsets`: Listen for changes to active clock offsets. When invoked the
callback will be provided with the new clock offsets.
* `clockOffsets`: A [clock offsets](#clock-offsets) object.
* `bounds`: emitted whenever the bounds change. The callback will be invoked
with two arguments:
* `bounds`: A [bounds](#getting-and-setting-bounds) bounds object
representing a new time period bound by the specified start and send times.
* `tick`: A `boolean` indicating whether or not this bounds change is due to
a "tick" from a [clock source](#clocks). This information can be useful
when determining a strategy for fetching telemetry data in response to a
bounds change event. For example, if the bounds change was automatic, and
is due to a tick then it's unlikely that you would need to perform a
historical data query. It should be sufficient to just show any new
telemetry received via subscription since the last tick, and optionally to
discard any older data that now falls outside of the currently set bounds.
If `tick` is false,then the bounds change was not due to an automatic tick,
and a query for historical data may be necessary, depending on your data
caching strategy, and how significantly the start bound has changed.
* `timeSystem`: emitted whenever the active time system changes. The callback will be invoked with a single argument:
* `timeSystem`: The newly active [time system](#defining-and-registering-time-systems).
* `clock`: emitted whenever the clock changes. The callback will be invoked
with a single argument:
* `clock`: The newly active [clock](#clocks), or `undefined` if an active
clock has been deactivated.
* `clockOffsets`: emitted whenever the active clock offsets change. The
callback will be invoked with a single argument:
* `clockOffsets`: The new [clock offsets](#clock-offsets).
## The Time Conductor
The Time Conductor provides a user interface for managing time bounds in Open MCT.
It allows a user to select from configured time systems and clocks, and to set bounds
and clock offsets.
The Time Conductor provides a user interface for managing time bounds in Open
MCT. It allows a user to select from configured time systems and clocks, and to set bounds and clock offsets.
If activated, the time conductor must be provided with configuration options,
detailed below.

3
index.html
View File

@ -43,7 +43,8 @@
openmct.install(openmct.plugins.Espresso());
openmct.install(openmct.plugins.Generator());
openmct.install(openmct.plugins.UTCTimeSystem());
openmct.time.timeSystem("utc", {start: Date.now() - THIRTY_MINUTES, end: Date.now()});
openmct.time.clock('local', {start: -THIRTY_MINUTES, end: 0});
openmct.time.timeSystem('utc');
openmct.start();
});
</script>

15
platform/features/conductor/core/src/ui/TimeConductorController.js
View File

@ -19,7 +19,6 @@
* this source code distribution or the Licensing information page available
* at runtime from the About dialog for additional information.
*****************************************************************************/
/* global console*/
define(
[
@ -98,7 +97,6 @@ define(
this.validation = new TimeConductorValidation(this.timeAPI);
this.formatService = formatService;
this.config = config;
this.clocksForTimeSystem = {};
this.timeSystemsForClocks = {};
this.$scope.timeSystemModel = {};
this.$scope.boundsModel = {};
@ -209,28 +207,17 @@ define(
cssClass: 'icon-calendar'
}];
var clocks = {};
var clocksForTimeSystem = this.clocksForTimeSystem;
var timeSystemsForClocks = this.timeSystemsForClocks;
(config.menuOptions || []).forEach(function (menuOption) {
var clock = this.getClock(menuOption.clock);
var clockKey = menuOption.clock || 'fixed';
var timeSystem = this.timeSystems[menuOption.timeSystem];
if (timeSystem !== undefined) {
if (clock !== undefined) {
// Use an associative array to built a set of unique
// clocks
clocks[clock.key] = clock;
clocksForTimeSystem[timeSystem.key] = clocksForTimeSystem[timeSystem.key] || [];
clocksForTimeSystem[timeSystem.key].push(clock);
}
timeSystemsForClocks[clockKey] = timeSystemsForClocks[clockKey] || [];
timeSystemsForClocks[clockKey].push(timeSystem);
} else if (menuOption.clock !== undefined) {
console.error('Unknown clock "' + clockKey + '", has it been registered?');
}
}.bind(this));
}, this);
/*
* Populate the clocks menu with metadata from the available clocks

2
src/adapter/directives/MCTView.js
View File

@ -22,7 +22,7 @@
define([
'angular',
'./Region',
'./Region'
], function (
angular,
Region

2
src/api/composition/CompositionCollection.js
View File

@ -21,7 +21,7 @@
*****************************************************************************/
define([
'lodash',
'lodash'
], function (
_
) {

2
src/api/telemetry/TelemetryAPI.js
View File

@ -23,7 +23,7 @@
define([
'./TelemetryMetadataManager',
'./TelemetryValueFormatter',
'lodash',
'lodash'
], function (
TelemetryMetadataManager,
TelemetryValueFormatter,

24
src/api/time/TimeAPI.js
View File

@ -239,7 +239,13 @@ define(['EventEmitter'], function (EventEmitter) {
* @method timeSystem
*/
TimeAPI.prototype.timeSystem = function (timeSystemOrKey, bounds) {
if (arguments.length >= 2) {
if (arguments.length >= 1) {
if (arguments.length === 1 && !this.activeClock) {
throw new Error(
"Must specify bounds when changing time system without " +
"an active clock."
);
}
var timeSystem;
if (timeSystemOrKey === undefined) {
@ -274,10 +280,10 @@ define(['EventEmitter'], function (EventEmitter) {
* Time System
* */
this.emit('timeSystem', this.system);
this.bounds(bounds);
if (bounds) {
this.bounds(bounds);
}
} else if (arguments.length === 1) {
throw new Error('Must set bounds when changing time system');
}
return this.system;
@ -366,11 +372,6 @@ define(['EventEmitter'], function (EventEmitter) {
this.activeClock = clock;
if (this.activeClock !== undefined) {
this.offsets = offsets;
this.activeClock.on("tick", this.tick);
}
/**
* The active clock has changed. Clock can be unset by calling {@link stopClock}
* @event clock
@ -380,6 +381,11 @@ define(['EventEmitter'], function (EventEmitter) {
*/
this.emit("clock", this.activeClock);
if (this.activeClock !== undefined) {
this.clockOffsets(offsets);
this.activeClock.on("tick", this.tick);
}
} else if (arguments.length === 1) {
throw "When setting the clock, clock offsets must also be provided";
}

47
src/api/time/TimeAPISpec.js
View File

@ -25,6 +25,8 @@ define(['./TimeAPI'], function (TimeAPI) {
var api,
timeSystemKey,
timeSystem,
clockKey,
clock,
bounds,
eventListener,
toi;
@ -33,7 +35,15 @@ define(['./TimeAPI'], function (TimeAPI) {
api = new TimeAPI();
timeSystemKey = "timeSystemKey";
timeSystem = {key: timeSystemKey};
bounds = {start: 0, end: 0};
clockKey = "someClockKey";
clock = jasmine.createSpyObj("clock", [
"on",
"off",
"currentValue"
]);
clock.currentValue.andReturn(100);
clock.key = clockKey;
bounds = {start: 0, end: 1};
eventListener = jasmine.createSpy("eventListener");
toi = 111;
});
@ -74,11 +84,23 @@ define(['./TimeAPI'], function (TimeAPI) {
it("Disallows setting of time system without bounds", function () {
api.addTimeSystem(timeSystem);
expect(api.timeSystem()).not.toBe(timeSystemKey);
expect(api.timeSystem()).not.toBe(timeSystem);
expect(function () {
api.timeSystem(timeSystemKey);
}).toThrow();
expect(api.timeSystem()).not.toBe(timeSystemKey);
expect(api.timeSystem()).not.toBe(timeSystem);
});
it("allows setting of timesystem without bounds with clock", function () {
api.addTimeSystem(timeSystem);
api.addClock(clock);
api.clock(clockKey, {start: 0, end: 1});
expect(api.timeSystem()).not.toBe(timeSystem);
expect(function () {
api.timeSystem(timeSystemKey);
}).not.toThrow();
expect(api.timeSystem()).toBe(timeSystem);
});
it("Emits an event when time system changes", function () {
@ -136,26 +158,35 @@ define(['./TimeAPI'], function (TimeAPI) {
var anotherMockTickSource;
var mockOffsets = {
start: 0,
end: 0
end: 1
};
beforeEach(function () {
mockTickSource = jasmine.createSpyObj("clock", [
"on",
"off"
"off",
"currentValue"
]);
mockTickSource.currentValue.andReturn(10);
mockTickSource.key = "mts";
anotherMockTickSource = jasmine.createSpyObj("clock", [
"on",
"off"
"off",
"currentValue"
]);
anotherMockTickSource.key = "amts";
anotherMockTickSource.currentValue.andReturn(10);
api.addClock(mockTickSource);
api.addClock(anotherMockTickSource);
});
it("sets bounds based on current value", function () {
api.clock("mts", mockOffsets);
expect(api.bounds()).toEqual({start: 10, end: 11});
});
it("a new tick listener is registered", function () {
api.clock("mts", mockOffsets);
expect(mockTickSource.on).toHaveBeenCalledWith("tick", jasmine.any(Function));
@ -180,8 +211,10 @@ define(['./TimeAPI'], function (TimeAPI) {
it("on tick, observes offsets, and indicates tick in bounds callback", function () {
var mockTickSource = jasmine.createSpyObj("clock", [
"on",
"off"
"off",
"currentValue"
]);
mockTickSource.currentValue.andReturn(100);
var tickCallback;
var boundsCallback = jasmine.createSpy("boundsCallback");
var clockOffsets = {

124
src/plugins/timeConductor/plugin.js
View File

@ -22,28 +22,79 @@
define([], function () {
function isTruthy(a) {
return !!a;
}
function validateMenuOption(menuOption, index) {
if (menuOption.clock && !menuOption.clockOffsets) {
return "clock-based menuOption at index " + index + " is " +
"missing required property 'clockOffsets'.";
}
if (!menuOption.timeSystem) {
return "menuOption at index " + index + " is missing " +
"required property 'timeSystem'.";
}
if (!menuOption.bounds && !menuOption.clock) {
return "fixed-bounds menuOption at index " + index + " is " +
"missing required property 'bounds'";
}
}
function validateConfiguration(config) {
if (config === undefined ||
config.menuOptions === undefined ||
config.menuOptions.length === 0) {
return "You must specify one or more 'menuOptions'.";
}
if (config.menuOptions.some(validateMenuOption)) {
return config.menuOptions.map(validateMenuOption)
.filter(isTruthy)
.join('\n');
}
return undefined;
}
function validateRuntimeConfiguration(config, openmct) {
var systems = openmct.time.getAllTimeSystems()
.reduce(function (m, ts) {
m[ts.key] = ts;
return m;
}, {});
var clocks = openmct.time.getAllClocks()
.reduce(function (m, c) {
m[c.key] = c;
return m;
}, {});
return config.menuOptions.map(function (menuOption, index) {
if (menuOption.timeSystem && !systems[menuOption.timeSystem]) {
return "menuOption at index " + index + " specifies a " +
"timeSystem that does not exist: " + menuOption.timeSystem;
}
if (menuOption.clock && !clocks[menuOption.clock]) {
return "menuOption at index " + index + " specifies a " +
"clock that does not exist: " + menuOption.clock;
}
})
.filter(isTruthy)
.join('\n');
}
function throwConfigErrorIfExists(error) {
if (error) {
throw new Error("Invalid Time Conductor Configuration: \n" +
error + '\n' +
"https://github.com/nasa/openmct/blob/master/API.md#the-time-conductor");
}
}
return function (config) {
function validateConfiguration() {
if (config === undefined || config.menuOptions === undefined || config.menuOptions.length === 0) {
return "Please provide some configuration for the time conductor. https://github.com/nasa/openmct/blob/master/API.md#the-time-conductor";
}
return undefined;
}
throwConfigErrorIfExists(validateConfiguration(config));
return function (openmct) {
function getTimeSystem(key) {
return openmct.time.getAllTimeSystems().filter(function (timeSystem) {
return timeSystem.key === key;
})[0];
}
var validationError = validateConfiguration();
if (validationError) {
throw validationError;
}
openmct.legacyExtension('constants', {
key: 'CONDUCTOR_CONFIG',
value: config,
@ -54,39 +105,24 @@ define([], function () {
openmct.legacyRegistry.enable('platform/features/conductor/compatibility');
openmct.on('start', function () {
throwConfigErrorIfExists(validateRuntimeConfiguration(config, openmct));
/*
On app startup, default the conductor
On app startup, default the conductor if not already set.
*/
var timeSystem = openmct.time.timeSystem();
var clock = openmct.time.clock();
if (timeSystem === undefined) {
timeSystem = getTimeSystem(config.menuOptions[0].timeSystem);
if (timeSystem === undefined) {
throw 'Please install and configure at least one time system';
}
if (openmct.time.timeSystem() !== undefined) {
return;
}
var configForTimeSystem = config.menuOptions.filter(function (menuOption) {
return menuOption.timeSystem === timeSystem.key && menuOption.clock === (clock && clock.key);
})[0];
if (configForTimeSystem !== undefined) {
var bounds;
if (clock === undefined) {
bounds = configForTimeSystem.bounds;
} else {
var clockOffsets = configForTimeSystem.clockOffsets;
bounds = {
start: clock.currentValue() + clockOffsets.start,
end: clock.currentValue() + clockOffsets.end
};
}
openmct.time.timeSystem(timeSystem, bounds);
var defaults = config.menuOptions[0];
if (defaults.clock) {
openmct.time.clock(defaults.clock, defaults.clockOffsets);
openmct.time.timeSystem(defaults.timeSystem, openmct.time.bounds());
} else {
throw 'Invalid time conductor configuration. Please define defaults for time system "' + timeSystem.key + '"';
openmct.time.timeSystem(defaults.timeSystem, defaults.bounds);
}
});
};
};