-
Notifications
You must be signed in to change notification settings - Fork 4
/
Datum.java
184 lines (164 loc) · 4.91 KB
/
Datum.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
/* ===================================================================
* Datum.java
*
* Created Nov 30, 2009 4:50:28 PM
*
* Copyright 2007-2009 SolarNetwork.net Dev Team
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License as
* published by the Free Software Foundation; either version 2 of
* the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
* 02111-1307 USA
* ===================================================================
*/
package net.solarnetwork.domain.datum;
import java.time.Instant;
import java.util.Map;
/**
* Basic persistable domain object API.
*
* @author matt
* @version 2.0
*/
public interface Datum {
/**
* A suffix to append to to data property keys that represent a logical
* reverse of the same key without this suffix. For example a
* <code>wattHoursReverse</code> key might represent energy exported, rather
* than imported, through a power meter.
*/
String REVERSE_ACCUMULATING_SUFFIX_KEY = "Reverse";
/**
* A property name for the string name of the <em>core</em> datum type a
* datum represents.
*
* <p>
* The <em>core</em> data type is the most specific interface defined on a
* datum class, which will be the first value in the
* {@link #DATUM_TYPES_PROPERTY} property.
* </p>
*
* @see #DATUM_TYPES_PROPERTY
*/
String DATUM_TYPE_PROPERTY = "_DatumType";
/**
* A property name for an array of string names of all datum types
* associated with the event.
*
* <p>
* Datum types are the fully qualified <em>interfaces</em> defined on the
* datum implementation class, and any superclass. All Java language
* interfaces are ignored, e.g. packages starting with {@literal java.} or
* {@literal javax.} are not included. The array is ordered in reverse class
* hierarchy order.
* </p>
*/
String DATUM_TYPES_PROPERTY = "_DatumTypes";
/**
* A status sample key for a
* {@link net.solarnetwork.domain.DeviceOperatingState#getCode()} value.
*/
String OP_STATE = "opState";
/**
* A status sample key for a bitmask of hardware-specific operating state
* values.
*/
String OP_STATES = "opStates";
/**
* A sample data key for a {@link Datum#getTimestamp()} value, as a
* {@code long} millisecond epoch value or ISO 8601 formatted string.
*/
String TIMESTAMP = "created";
/**
* A sample data key for a {@link Datum#getSourceId()} value.
*/
String SOURCE_ID = "sourceId";
/**
* Get the object kind.
*
* @return the object kind
*/
ObjectDatumKind getKind();
/**
* Get a domain-specific ID related to the object kind.
*
* @return the object ID, or {@literal null}
*/
Long getObjectId();
/**
* Get the date this datum is associated with, which is often equal to
* either the date it was persisted or the date the associated data in this
* object was captured.
*
* @return the timestamp
*/
Instant getTimestamp();
/**
* Get a unique source ID for this datum.
*
* <p>
* A single datum type may collect data from many different sources.
* </p>
*
* @return the source ID
*/
String getSourceId();
/**
* Get a map of all available data sampled or collected on this datum.
*
* @return a map with all available sample data
*/
Map<String, ?> getSampleData();
/**
* Get a simple {@link Map} view of this datum.
*
* <p>
* The returned map should include all the available properties of this
* datum, in as flat of a structure as possible, i.e. without nested maps.
* The property values should be composed only if simple Java types like
* numbers, strings, and arrays or lists of those types. It should also
* include the {@link #DATUM_TYPE_PROPERTY} and
* {@link #DATUM_TYPES_PROPERTY} values.
* </p>
*
* @return a Map view of this datum
*/
Map<String, ?> asSimpleMap();
/**
* Get a general accessor for the sample data.
*
* @return the operations instance, never {@literal null}
*/
DatumSamplesOperations asSampleOperations();
/**
* Create a copy of this instance with the sample properties replaced by a
* given samples instance.
*
* @param samples
* the samples to use for the copy
* @return a new copy of this instance
*/
Datum copyWithSamples(DatumSamplesOperations samples);
/**
* Get a copy of this datum with a new ID.
*
* <p>
* A new samples instance will also be created.
* </p>
*
* @param id
* the new ID to use
* @return the copy with the given ID
*/
Datum copyWithId(DatumId id);
}