简柏林 / thingskit · Commits

Commit 90f7ff57d53ed0d9a5bbae08b1fb2152467f9826

Authored by Andrii Shvaika
2 parents afbf18d8 d17ea19b

Entity Relations Draft

Inline Side-by-side
Showing 8 changed files with 132 additions and 36 deletions
@@ -196,13 +196,15 @@ public abstract class BaseController { @@ -196,13 +196,15 @@ public abstract class BaseController {
196 protected final String DEVICE_INFO_DESCRIPTION = "Device Info is an extension of the default Device object that contains information about the assigned customer name and device profile name. "; 196 protected final String DEVICE_INFO_DESCRIPTION = "Device Info is an extension of the default Device object that contains information about the assigned customer name and device profile name. ";
197 protected final String ASSET_INFO_DESCRIPTION = "Asset Info is an extension of the default Asset object that contains information about the assigned customer name. "; 197 protected final String ASSET_INFO_DESCRIPTION = "Asset Info is an extension of the default Asset object that contains information about the assigned customer name. ";
198 protected final String ALARM_INFO_DESCRIPTION = "Alarm Info is an extension of the default Alarm object that also contains name of the alarm originator."; 198 protected final String ALARM_INFO_DESCRIPTION = "Alarm Info is an extension of the default Alarm object that also contains name of the alarm originator.";
199 - 199 + protected final String RELATION_INFO_DESCRIPTION = "Relation Info is an extension of the default Relation object that contains information about the 'from' and 'to' entity names. ";
200 200
201 protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name."; 201 protected final String DEVICE_NAME_DESCRIPTION = "A string value representing the Device name.";
202 protected final String ASSET_NAME_DESCRIPTION = "A string value representing the Asset name."; 202 protected final String ASSET_NAME_DESCRIPTION = "A string value representing the Asset name.";
203 203
204 protected final String EVENT_START_TIME_DESCRIPTION = "Timestamp. Events with creation time before it won't be queried."; 204 protected final String EVENT_START_TIME_DESCRIPTION = "Timestamp. Events with creation time before it won't be queried.";
205 protected final String EVENT_END_TIME_DESCRIPTION = "Timestamp. Events with creation time after it won't be queried."; 205 protected final String EVENT_END_TIME_DESCRIPTION = "Timestamp. Events with creation time after it won't be queried.";
  206 + protected static final String RELATION_TYPE_PARAM_DESCRIPTION = "A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value.";
  207 + protected static final String RELATION_TYPE_GROUP_PARAM_DESCRIPTION = "A string value representing relation type group. For example, 'COMMON'";
206 208
207 public static final String INCORRECT_TENANT_ID = "Incorrect tenantId "; 209 public static final String INCORRECT_TENANT_ID = "Incorrect tenantId ";
208 protected static final String DEFAULT_DASHBOARD = "defaultDashboardId"; 210 protected static final String DEFAULT_DASHBOARD = "defaultDashboardId";
@@ -15,7 +15,10 @@ @@ -15,7 +15,10 @@
15 */ 15 */
16 package org.thingsboard.server.controller; 16 package org.thingsboard.server.controller;
17 17
  18 +import io.swagger.annotations.ApiOperation;
  19 +import io.swagger.annotations.ApiParam;
18 import org.springframework.http.HttpStatus; 20 import org.springframework.http.HttpStatus;
  21 +import org.springframework.http.MediaType;
19 import org.springframework.security.access.prepost.PreAuthorize; 22 import org.springframework.security.access.prepost.PreAuthorize;
20 import org.springframework.web.bind.annotation.RequestBody; 23 import org.springframework.web.bind.annotation.RequestBody;
21 import org.springframework.web.bind.annotation.RequestMapping; 24 import org.springframework.web.bind.annotation.RequestMapping;
@@ -52,10 +55,26 @@ public class EntityRelationController extends BaseController { @@ -52,10 +55,26 @@ public class EntityRelationController extends BaseController {
52 public static final String RELATION_TYPE = "relationType"; 55 public static final String RELATION_TYPE = "relationType";
53 public static final String TO_ID = "toId"; 56 public static final String TO_ID = "toId";
54 57
  58 + private static final String SECURITY_CHECKS_ENTITIES_DESCRIPTION = "\n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. " +
  59 + "If the user has the authority of 'Tenant Administrator', the server checks that 'from' and 'to' entities are owned by the same tenant. " +
  60 + "If the user has the authority of 'Customer User', the server checks that the 'from' and 'to' entities are assigned to the same customer.";
  61 +
  62 + private static final String SECURITY_CHECKS_ENTITY_DESCRIPTION = "\n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. " +
  63 + "If the user has the authority of 'Tenant Administrator', the server checks that the entity is owned by the same tenant. " +
  64 + "If the user has the authority of 'Customer User', the server checks that the entity is assigned to the same customer.";
  65 +
  66 +
  67 + @ApiOperation(value = "Create Relation (saveRelation)",
  68 + notes = "Creates or updates a relation between two entities in the platform. " +
  69 + "Relations unique key is a combination of from/to entity id and relation type group and relation type. " +
  70 + "\n\nIf the user has the authority of 'System Administrator', the server checks that 'from' and 'to' entities are owned by the sysadmin. " +
  71 + "If the user has the authority of 'Tenant Administrator', the server checks that 'from' and 'to' entities are owned by the same tenant. " +
  72 + "If the user has the authority of 'Customer User', the server checks that the 'from' and 'to' entities are assigned to the same customer.")
55 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 73 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
56 @RequestMapping(value = "/relation", method = RequestMethod.POST) 74 @RequestMapping(value = "/relation", method = RequestMethod.POST)
57 @ResponseStatus(value = HttpStatus.OK) 75 @ResponseStatus(value = HttpStatus.OK)
58 - public void saveRelation(@RequestBody EntityRelation relation) throws ThingsboardException { 76 + public void saveRelation(@ApiParam(value = "A JSON value representing the relation.", required = true)
  77 + @RequestBody EntityRelation relation) throws ThingsboardException {
59 try { 78 try {
60 checkNotNull(relation); 79 checkNotNull(relation);
61 checkEntityId(relation.getFrom(), Operation.WRITE); 80 checkEntityId(relation.getFrom(), Operation.WRITE);
@@ -80,14 +99,17 @@ public class EntityRelationController extends BaseController { @@ -80,14 +99,17 @@ public class EntityRelationController extends BaseController {
80 } 99 }
81 } 100 }
82 101
  102 + @ApiOperation(value = "Delete Relation (deleteRelation)",
  103 + notes = "Deletes a relation between two entities in the platform. " + SECURITY_CHECKS_ENTITIES_DESCRIPTION)
83 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 104 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
84 @RequestMapping(value = "/relation", method = RequestMethod.DELETE, params = {FROM_ID, FROM_TYPE, RELATION_TYPE, TO_ID, TO_TYPE}) 105 @RequestMapping(value = "/relation", method = RequestMethod.DELETE, params = {FROM_ID, FROM_TYPE, RELATION_TYPE, TO_ID, TO_TYPE})
85 @ResponseStatus(value = HttpStatus.OK) 106 @ResponseStatus(value = HttpStatus.OK)
86 - public void deleteRelation(@RequestParam(FROM_ID) String strFromId,  
87 - @RequestParam(FROM_TYPE) String strFromType,  
88 - @RequestParam(RELATION_TYPE) String strRelationType,  
89 - @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup,  
90 - @RequestParam(TO_ID) String strToId, @RequestParam(TO_TYPE) String strToType) throws ThingsboardException { 107 + public void deleteRelation(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(FROM_ID) String strFromId,
  108 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(FROM_TYPE) String strFromType,
  109 + @ApiParam(value = RELATION_TYPE_PARAM_DESCRIPTION, required = true) @RequestParam(RELATION_TYPE) String strRelationType,
  110 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION) @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup,
  111 + @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(TO_ID) String strToId,
  112 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(TO_TYPE) String strToType) throws ThingsboardException {
91 checkParameter(FROM_ID, strFromId); 113 checkParameter(FROM_ID, strFromId);
92 checkParameter(FROM_TYPE, strFromType); 114 checkParameter(FROM_TYPE, strFromType);
93 checkParameter(RELATION_TYPE, strRelationType); 115 checkParameter(RELATION_TYPE, strRelationType);
@@ -119,11 +141,14 @@ public class EntityRelationController extends BaseController { @@ -119,11 +141,14 @@ public class EntityRelationController extends BaseController {
119 } 141 }
120 } 142 }
121 143
  144 + @ApiOperation(value = "Delete Relations (deleteRelations)",
  145 + notes = "Deletes all the relation (both 'from' and 'to' direction) for the specified entity. " +
  146 + SECURITY_CHECKS_ENTITY_DESCRIPTION)
122 @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN', 'CUSTOMER_USER')") 147 @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN', 'CUSTOMER_USER')")
123 - @RequestMapping(value = "/relations", method = RequestMethod.DELETE, params = {"id", "type"}) 148 + @RequestMapping(value = "/relations", method = RequestMethod.DELETE, params = {"entityId", "entityType"})
124 @ResponseStatus(value = HttpStatus.OK) 149 @ResponseStatus(value = HttpStatus.OK)
125 - public void deleteRelations(@RequestParam("entityId") String strId,  
126 - @RequestParam("entityType") String strType) throws ThingsboardException { 150 + public void deleteRelations(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam("entityId") String strId,
  151 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam("entityType") String strType) throws ThingsboardException {
127 checkParameter("entityId", strId); 152 checkParameter("entityId", strId);
128 checkParameter("entityType", strType); 153 checkParameter("entityType", strType);
129 EntityId entityId = EntityIdFactory.getByTypeAndId(strType, strId); 154 EntityId entityId = EntityIdFactory.getByTypeAndId(strType, strId);
@@ -137,14 +162,18 @@ public class EntityRelationController extends BaseController { @@ -137,14 +162,18 @@ public class EntityRelationController extends BaseController {
137 } 162 }
138 } 163 }
139 164
  165 + @ApiOperation(value = "Get Relation (getRelation)",
  166 + notes = "Returns relation object between two specified entities if present. Otherwise throws exception." + SECURITY_CHECKS_ENTITIES_DESCRIPTION,
  167 + produces = MediaType.APPLICATION_JSON_VALUE)
140 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 168 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
141 @RequestMapping(value = "/relation", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE, RELATION_TYPE, TO_ID, TO_TYPE}) 169 @RequestMapping(value = "/relation", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE, RELATION_TYPE, TO_ID, TO_TYPE})
142 @ResponseBody 170 @ResponseBody
143 - public EntityRelation getRelation(@RequestParam(FROM_ID) String strFromId,  
144 - @RequestParam(FROM_TYPE) String strFromType,  
145 - @RequestParam(RELATION_TYPE) String strRelationType,  
146 - @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup,  
147 - @RequestParam(TO_ID) String strToId, @RequestParam(TO_TYPE) String strToType) throws ThingsboardException { 171 + public EntityRelation getRelation(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(FROM_ID) String strFromId,
  172 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(FROM_TYPE) String strFromType,
  173 + @ApiParam(value = RELATION_TYPE_PARAM_DESCRIPTION, required = true) @RequestParam(RELATION_TYPE) String strRelationType,
  174 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION) @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup,
  175 + @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(TO_ID) String strToId,
  176 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(TO_TYPE) String strToType) throws ThingsboardException {
148 try { 177 try {
149 checkParameter(FROM_ID, strFromId); 178 checkParameter(FROM_ID, strFromId);
150 checkParameter(FROM_TYPE, strFromType); 179 checkParameter(FROM_TYPE, strFromType);
@@ -162,11 +191,16 @@ public class EntityRelationController extends BaseController { @@ -162,11 +191,16 @@ public class EntityRelationController extends BaseController {
162 } 191 }
163 } 192 }
164 193
  194 + @ApiOperation(value = "Get List of Relations (findByFrom)",
  195 + notes = "Returns list of relation objects for the specified entity by the 'from' direction. " +
  196 + SECURITY_CHECKS_ENTITY_DESCRIPTION,
  197 + produces = MediaType.APPLICATION_JSON_VALUE)
165 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 198 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
166 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE}) 199 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE})
167 @ResponseBody 200 @ResponseBody
168 - public List<EntityRelation> findByFrom(@RequestParam(FROM_ID) String strFromId,  
169 - @RequestParam(FROM_TYPE) String strFromType, 201 + public List<EntityRelation> findByFrom(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(FROM_ID) String strFromId,
  202 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(FROM_TYPE) String strFromType,
  203 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION)
170 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException { 204 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException {
171 checkParameter(FROM_ID, strFromId); 205 checkParameter(FROM_ID, strFromId);
172 checkParameter(FROM_TYPE, strFromType); 206 checkParameter(FROM_TYPE, strFromType);
@@ -180,11 +214,16 @@ public class EntityRelationController extends BaseController { @@ -180,11 +214,16 @@ public class EntityRelationController extends BaseController {
180 } 214 }
181 } 215 }
182 216
  217 + @ApiOperation(value = "Get List of Relation Infos (findInfoByFrom)",
  218 + notes = "Returns list of relation info objects for the specified entity by the 'from' direction. " +
  219 + SECURITY_CHECKS_ENTITY_DESCRIPTION +" " + RELATION_INFO_DESCRIPTION,
  220 + produces = MediaType.APPLICATION_JSON_VALUE)
183 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 221 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
184 @RequestMapping(value = "/relations/info", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE}) 222 @RequestMapping(value = "/relations/info", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE})
185 @ResponseBody 223 @ResponseBody
186 - public List<EntityRelationInfo> findInfoByFrom(@RequestParam(FROM_ID) String strFromId,  
187 - @RequestParam(FROM_TYPE) String strFromType, 224 + public List<EntityRelationInfo> findInfoByFrom(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(FROM_ID) String strFromId,
  225 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(FROM_TYPE) String strFromType,
  226 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION)
188 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException { 227 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException {
189 checkParameter(FROM_ID, strFromId); 228 checkParameter(FROM_ID, strFromId);
190 checkParameter(FROM_TYPE, strFromType); 229 checkParameter(FROM_TYPE, strFromType);
@@ -198,12 +237,17 @@ public class EntityRelationController extends BaseController { @@ -198,12 +237,17 @@ public class EntityRelationController extends BaseController {
198 } 237 }
199 } 238 }
200 239
  240 + @ApiOperation(value = "Get List of Relations (findByFrom)",
  241 + notes = "Returns list of relation objects for the specified entity by the 'from' direction and relation type. " +
  242 + SECURITY_CHECKS_ENTITY_DESCRIPTION,
  243 + produces = MediaType.APPLICATION_JSON_VALUE)
201 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 244 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
202 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE, RELATION_TYPE}) 245 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {FROM_ID, FROM_TYPE, RELATION_TYPE})
203 @ResponseBody 246 @ResponseBody
204 - public List<EntityRelation> findByFrom(@RequestParam(FROM_ID) String strFromId,  
205 - @RequestParam(FROM_TYPE) String strFromType,  
206 - @RequestParam(RELATION_TYPE) String strRelationType, 247 + public List<EntityRelation> findByFrom(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(FROM_ID) String strFromId,
  248 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(FROM_TYPE) String strFromType,
  249 + @ApiParam(value = RELATION_TYPE_PARAM_DESCRIPTION, required = true) @RequestParam(RELATION_TYPE) String strRelationType,
  250 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION)
207 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException { 251 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException {
208 checkParameter(FROM_ID, strFromId); 252 checkParameter(FROM_ID, strFromId);
209 checkParameter(FROM_TYPE, strFromType); 253 checkParameter(FROM_TYPE, strFromType);
@@ -218,11 +262,16 @@ public class EntityRelationController extends BaseController { @@ -218,11 +262,16 @@ public class EntityRelationController extends BaseController {
218 } 262 }
219 } 263 }
220 264
  265 + @ApiOperation(value = "Get List of Relations (findByTo)",
  266 + notes = "Returns list of relation objects for the specified entity by the 'to' direction. " +
  267 + SECURITY_CHECKS_ENTITY_DESCRIPTION,
  268 + produces = MediaType.APPLICATION_JSON_VALUE)
221 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 269 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
222 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {TO_ID, TO_TYPE}) 270 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {TO_ID, TO_TYPE})
223 @ResponseBody 271 @ResponseBody
224 - public List<EntityRelation> findByTo(@RequestParam(TO_ID) String strToId,  
225 - @RequestParam(TO_TYPE) String strToType, 272 + public List<EntityRelation> findByTo(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(TO_ID) String strToId,
  273 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(TO_TYPE) String strToType,
  274 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION)
226 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException { 275 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException {
227 checkParameter(TO_ID, strToId); 276 checkParameter(TO_ID, strToId);
228 checkParameter(TO_TYPE, strToType); 277 checkParameter(TO_TYPE, strToType);
@@ -236,11 +285,16 @@ public class EntityRelationController extends BaseController { @@ -236,11 +285,16 @@ public class EntityRelationController extends BaseController {
236 } 285 }
237 } 286 }
238 287
  288 + @ApiOperation(value = "Get List of Relation Infos (findInfoByTo)",
  289 + notes = "Returns list of relation info objects for the specified entity by the 'to' direction. " +
  290 + SECURITY_CHECKS_ENTITY_DESCRIPTION + " " + RELATION_INFO_DESCRIPTION,
  291 + produces = MediaType.APPLICATION_JSON_VALUE)
239 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 292 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
240 @RequestMapping(value = "/relations/info", method = RequestMethod.GET, params = {TO_ID, TO_TYPE}) 293 @RequestMapping(value = "/relations/info", method = RequestMethod.GET, params = {TO_ID, TO_TYPE})
241 @ResponseBody 294 @ResponseBody
242 - public List<EntityRelationInfo> findInfoByTo(@RequestParam(TO_ID) String strToId,  
243 - @RequestParam(TO_TYPE) String strToType, 295 + public List<EntityRelationInfo> findInfoByTo(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(TO_ID) String strToId,
  296 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(TO_TYPE) String strToType,
  297 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION)
244 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException { 298 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException {
245 checkParameter(TO_ID, strToId); 299 checkParameter(TO_ID, strToId);
246 checkParameter(TO_TYPE, strToType); 300 checkParameter(TO_TYPE, strToType);
@@ -254,12 +308,17 @@ public class EntityRelationController extends BaseController { @@ -254,12 +308,17 @@ public class EntityRelationController extends BaseController {
254 } 308 }
255 } 309 }
256 310
  311 + @ApiOperation(value = "Get List of Relations (findByTo)",
  312 + notes = "Returns list of relation objects for the specified entity by the 'to' direction and relation type. " +
  313 + SECURITY_CHECKS_ENTITY_DESCRIPTION,
  314 + produces = MediaType.APPLICATION_JSON_VALUE)
257 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 315 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
258 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {TO_ID, TO_TYPE, RELATION_TYPE}) 316 @RequestMapping(value = "/relations", method = RequestMethod.GET, params = {TO_ID, TO_TYPE, RELATION_TYPE})
259 @ResponseBody 317 @ResponseBody
260 - public List<EntityRelation> findByTo(@RequestParam(TO_ID) String strToId,  
261 - @RequestParam(TO_TYPE) String strToType,  
262 - @RequestParam(RELATION_TYPE) String strRelationType, 318 + public List<EntityRelation> findByTo(@ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION, required = true) @RequestParam(TO_ID) String strToId,
  319 + @ApiParam(value = ENTITY_TYPE_DESCRIPTION, required = true) @RequestParam(TO_TYPE) String strToType,
  320 + @ApiParam(value = RELATION_TYPE_PARAM_DESCRIPTION, required = true) @RequestParam(RELATION_TYPE) String strRelationType,
  321 + @ApiParam(value = RELATION_TYPE_GROUP_PARAM_DESCRIPTION)
263 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException { 322 @RequestParam(value = "relationTypeGroup", required = false) String strRelationTypeGroup) throws ThingsboardException {
264 checkParameter(TO_ID, strToId); 323 checkParameter(TO_ID, strToId);
265 checkParameter(TO_TYPE, strToType); 324 checkParameter(TO_TYPE, strToType);
@@ -274,10 +333,15 @@ public class EntityRelationController extends BaseController { @@ -274,10 +333,15 @@ public class EntityRelationController extends BaseController {
274 } 333 }
275 } 334 }
276 335
  336 + @ApiOperation(value = "Find related entities (findByQuery)",
  337 + notes = "Returns all entities that are related to the specific entity. " +
  338 + "The entity id, relation type, entity types, depth of the search, and other query parameters defined using complex 'EntityRelationsQuery' object. " +
  339 + "See 'Model' tab of the Parameters for more info.", produces = MediaType.APPLICATION_JSON_VALUE)
277 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 340 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
278 @RequestMapping(value = "/relations", method = RequestMethod.POST) 341 @RequestMapping(value = "/relations", method = RequestMethod.POST)
279 @ResponseBody 342 @ResponseBody
280 - public List<EntityRelation> findByQuery(@RequestBody EntityRelationsQuery query) throws ThingsboardException { 343 + public List<EntityRelation> findByQuery(@ApiParam(value = "A JSON value representing the entity relations query object.", required = true)
  344 + @RequestBody EntityRelationsQuery query) throws ThingsboardException {
281 checkNotNull(query); 345 checkNotNull(query);
282 checkNotNull(query.getParameters()); 346 checkNotNull(query.getParameters());
283 checkNotNull(query.getFilters()); 347 checkNotNull(query.getFilters());
@@ -289,10 +353,15 @@ public class EntityRelationController extends BaseController { @@ -289,10 +353,15 @@ public class EntityRelationController extends BaseController {
289 } 353 }
290 } 354 }
291 355
  356 + @ApiOperation(value = "Find related entity infos (findInfoByQuery)",
  357 + notes = "Returns all entity infos that are related to the specific entity. " +
  358 + "The entity id, relation type, entity types, depth of the search, and other query parameters defined using complex 'EntityRelationsQuery' object. " +
  359 + "See 'Model' tab of the Parameters for more info. " + RELATION_INFO_DESCRIPTION, produces = MediaType.APPLICATION_JSON_VALUE)
292 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')") 360 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
293 @RequestMapping(value = "/relations/info", method = RequestMethod.POST) 361 @RequestMapping(value = "/relations/info", method = RequestMethod.POST)
294 @ResponseBody 362 @ResponseBody
295 - public List<EntityRelationInfo> findInfoByQuery(@RequestBody EntityRelationsQuery query) throws ThingsboardException { 363 + public List<EntityRelationInfo> findInfoByQuery(@ApiParam(value = "A JSON value representing the entity relations query object.", required = true)
  364 + @RequestBody EntityRelationsQuery query) throws ThingsboardException {
296 checkNotNull(query); 365 checkNotNull(query);
297 checkNotNull(query.getParameters()); 366 checkNotNull(query.getParameters());
298 checkNotNull(query.getFilters()); 367 checkNotNull(query.getFilters());
@@ -18,6 +18,8 @@ package org.thingsboard.server.common.data.id; @@ -18,6 +18,8 @@ package org.thingsboard.server.common.data.id;
18 import com.fasterxml.jackson.annotation.JsonIgnore; 18 import com.fasterxml.jackson.annotation.JsonIgnore;
19 import com.fasterxml.jackson.databind.annotation.JsonDeserialize; 19 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
20 import com.fasterxml.jackson.databind.annotation.JsonSerialize; 20 import com.fasterxml.jackson.databind.annotation.JsonSerialize;
  21 +import io.swagger.annotations.ApiModel;
  22 +import io.swagger.annotations.ApiModelProperty;
21 import org.thingsboard.server.common.data.EntityType; 23 import org.thingsboard.server.common.data.EntityType;
22 24
23 import java.io.Serializable; 25 import java.io.Serializable;
@@ -29,12 +31,15 @@ import java.util.UUID; @@ -29,12 +31,15 @@ import java.util.UUID;
29 31
30 @JsonDeserialize(using = EntityIdDeserializer.class) 32 @JsonDeserialize(using = EntityIdDeserializer.class)
31 @JsonSerialize(using = EntityIdSerializer.class) 33 @JsonSerialize(using = EntityIdSerializer.class)
  34 +@ApiModel
32 public interface EntityId extends HasUUID, Serializable { //NOSONAR, the constant is closely related to EntityId 35 public interface EntityId extends HasUUID, Serializable { //NOSONAR, the constant is closely related to EntityId
33 36
34 UUID NULL_UUID = UUID.fromString("13814000-1dd2-11b2-8080-808080808080"); 37 UUID NULL_UUID = UUID.fromString("13814000-1dd2-11b2-8080-808080808080");
35 38
  39 + @ApiModelProperty(position = 1, required = true, value = "string", example = "784f394c-42b6-435a-983c-b7beff2784f9")
36 UUID getId(); 40 UUID getId();
37 41
  42 + @ApiModelProperty(position = 2, required = true, value = "string", example = "DEVICE")
38 EntityType getEntityType(); 43 EntityType getEntityType();
39 44
40 @JsonIgnore 45 @JsonIgnore
@@ -16,18 +16,17 @@ @@ -16,18 +16,17 @@
16 package org.thingsboard.server.common.data.relation; 16 package org.thingsboard.server.common.data.relation;
17 17
18 import com.fasterxml.jackson.annotation.JsonIgnore; 18 import com.fasterxml.jackson.annotation.JsonIgnore;
19 -import com.fasterxml.jackson.core.JsonProcessingException;  
20 import com.fasterxml.jackson.databind.JsonNode; 19 import com.fasterxml.jackson.databind.JsonNode;
21 -import com.fasterxml.jackson.databind.ObjectMapper; 20 +import io.swagger.annotations.ApiModel;
  21 +import io.swagger.annotations.ApiModelProperty;
22 import lombok.extern.slf4j.Slf4j; 22 import lombok.extern.slf4j.Slf4j;
23 import org.thingsboard.server.common.data.SearchTextBasedWithAdditionalInfo; 23 import org.thingsboard.server.common.data.SearchTextBasedWithAdditionalInfo;
24 import org.thingsboard.server.common.data.id.EntityId; 24 import org.thingsboard.server.common.data.id.EntityId;
25 25
26 -import java.io.ByteArrayInputStream;  
27 -import java.io.IOException;  
28 import java.io.Serializable; 26 import java.io.Serializable;
29 27
30 @Slf4j 28 @Slf4j
  29 +@ApiModel
31 public class EntityRelation implements Serializable { 30 public class EntityRelation implements Serializable {
32 31
33 private static final long serialVersionUID = 2807343040519543363L; 32 private static final long serialVersionUID = 2807343040519543363L;
@@ -72,6 +71,7 @@ public class EntityRelation implements Serializable { @@ -72,6 +71,7 @@ public class EntityRelation implements Serializable {
72 this.additionalInfo = entityRelation.getAdditionalInfo(); 71 this.additionalInfo = entityRelation.getAdditionalInfo();
73 } 72 }
74 73
  74 + @ApiModelProperty(position = 1, value = "JSON object with [from] Entity Id.", readOnly = true)
75 public EntityId getFrom() { 75 public EntityId getFrom() {
76 return from; 76 return from;
77 } 77 }
@@ -80,6 +80,7 @@ public class EntityRelation implements Serializable { @@ -80,6 +80,7 @@ public class EntityRelation implements Serializable {
80 this.from = from; 80 this.from = from;
81 } 81 }
82 82
  83 + @ApiModelProperty(position = 2, value = "JSON object with [to] Entity Id.", readOnly = true)
83 public EntityId getTo() { 84 public EntityId getTo() {
84 return to; 85 return to;
85 } 86 }
@@ -88,6 +89,7 @@ public class EntityRelation implements Serializable { @@ -88,6 +89,7 @@ public class EntityRelation implements Serializable {
88 this.to = to; 89 this.to = to;
89 } 90 }
90 91
  92 + @ApiModelProperty(position = 3, value = "String value of relation type.", example = "Contains")
91 public String getType() { 93 public String getType() {
92 return type; 94 return type;
93 } 95 }
@@ -96,6 +98,7 @@ public class EntityRelation implements Serializable { @@ -96,6 +98,7 @@ public class EntityRelation implements Serializable {
96 this.type = type; 98 this.type = type;
97 } 99 }
98 100
  101 + @ApiModelProperty(position = 4, value = "Represents the type group of the relation.", example = "COMMON")
99 public RelationTypeGroup getTypeGroup() { 102 public RelationTypeGroup getTypeGroup() {
100 return typeGroup; 103 return typeGroup;
101 } 104 }
@@ -104,6 +107,7 @@ public class EntityRelation implements Serializable { @@ -104,6 +107,7 @@ public class EntityRelation implements Serializable {
104 this.typeGroup = typeGroup; 107 this.typeGroup = typeGroup;
105 } 108 }
106 109
  110 + @ApiModelProperty(position = 5, value = "Additional parameters of the relation", dataType = "com.fasterxml.jackson.databind.JsonNode")
107 public JsonNode getAdditionalInfo() { 111 public JsonNode getAdditionalInfo() {
108 return SearchTextBasedWithAdditionalInfo.getJson(() -> additionalInfo, () -> additionalInfoBytes); 112 return SearchTextBasedWithAdditionalInfo.getJson(() -> additionalInfo, () -> additionalInfoBytes);
109 } 113 }
@@ -15,6 +15,8 @@ @@ -15,6 +15,8 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.relation; 16 package org.thingsboard.server.common.data.relation;
17 17
  18 +import io.swagger.annotations.ApiModelProperty;
  19 +
18 public class EntityRelationInfo extends EntityRelation { 20 public class EntityRelationInfo extends EntityRelation {
19 21
20 private static final long serialVersionUID = 2807343097519543363L; 22 private static final long serialVersionUID = 2807343097519543363L;
@@ -30,6 +32,7 @@ public class EntityRelationInfo extends EntityRelation { @@ -30,6 +32,7 @@ public class EntityRelationInfo extends EntityRelation {
30 super(entityRelation); 32 super(entityRelation);
31 } 33 }
32 34
  35 + @ApiModelProperty(position = 6, value = "Name of the entity for [from] direction.", readOnly = true, example = "A4B72CCDFF33")
33 public String getFromName() { 36 public String getFromName() {
34 return fromName; 37 return fromName;
35 } 38 }
@@ -38,6 +41,7 @@ public class EntityRelationInfo extends EntityRelation { @@ -38,6 +41,7 @@ public class EntityRelationInfo extends EntityRelation {
38 this.fromName = fromName; 41 this.fromName = fromName;
39 } 42 }
40 43
  44 + @ApiModelProperty(position = 7, value = "Name of the entity for [to] direction.", readOnly = true, example = "A4B72CCDFF35")
41 public String getToName() { 45 public String getToName() {
42 return toName; 46 return toName;
43 } 47 }
@@ -15,6 +15,8 @@ @@ -15,6 +15,8 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.relation; 16 package org.thingsboard.server.common.data.relation;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.Data; 20 import lombok.Data;
19 21
20 import java.util.List; 22 import java.util.List;
@@ -23,9 +25,12 @@ import java.util.List; @@ -23,9 +25,12 @@ import java.util.List;
23 * Created by ashvayka on 02.05.17. 25 * Created by ashvayka on 02.05.17.
24 */ 26 */
25 @Data 27 @Data
  28 +@ApiModel
26 public class EntityRelationsQuery { 29 public class EntityRelationsQuery {
27 30
  31 + @ApiModelProperty(position = 2, value = "Main search parameters.")
28 private RelationsSearchParameters parameters; 32 private RelationsSearchParameters parameters;
  33 + @ApiModelProperty(position = 1, value = "Main filters.")
29 private List<RelationEntityTypeFilter> filters; 34 private List<RelationEntityTypeFilter> filters;
30 35
31 } 36 }
@@ -15,6 +15,8 @@ @@ -15,6 +15,8 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.relation; 16 package org.thingsboard.server.common.data.relation;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
18 import lombok.AllArgsConstructor; 20 import lombok.AllArgsConstructor;
19 import lombok.Data; 21 import lombok.Data;
20 import org.thingsboard.server.common.data.EntityType; 22 import org.thingsboard.server.common.data.EntityType;
@@ -26,9 +28,12 @@ import java.util.List; @@ -26,9 +28,12 @@ import java.util.List;
26 */ 28 */
27 @Data 29 @Data
28 @AllArgsConstructor 30 @AllArgsConstructor
  31 +@ApiModel
29 public class RelationEntityTypeFilter { 32 public class RelationEntityTypeFilter {
30 33
  34 + @ApiModelProperty(position = 1, value = "Type of the relation between root entity and other entity (e.g. 'Contains' or 'Manages').", example = "Contains")
31 private String relationType; 35 private String relationType;
32 36
  37 + @ApiModelProperty(position = 2, value = "Array of entity types to filter the related entities (e.g. 'DEVICE', 'ASSET').")
33 private List<EntityType> entityTypes; 38 private List<EntityType> entityTypes;
34 } 39 }
@@ -15,6 +15,7 @@ @@ -15,6 +15,7 @@
15 */ 15 */
16 package org.thingsboard.server.common.data.relation; 16 package org.thingsboard.server.common.data.relation;
17 17
  18 +import com.fasterxml.jackson.annotation.JsonIgnore;
18 import io.swagger.annotations.ApiModel; 19 import io.swagger.annotations.ApiModel;
19 import io.swagger.annotations.ApiModelProperty; 20 import io.swagger.annotations.ApiModelProperty;
20 import lombok.AllArgsConstructor; 21 import lombok.AllArgsConstructor;
@@ -33,7 +34,7 @@ import java.util.UUID; @@ -33,7 +34,7 @@ import java.util.UUID;
33 @AllArgsConstructor 34 @AllArgsConstructor
34 public class RelationsSearchParameters { 35 public class RelationsSearchParameters {
35 36
36 - @ApiModelProperty(position = 1, value = "Root entity id to start search from.") 37 + @ApiModelProperty(position = 1, value = "Root entity id to start search from.", example = "784f394c-42b6-435a-983c-b7beff2784f9")
37 private UUID rootId; 38 private UUID rootId;
38 @ApiModelProperty(position = 2, value = "Type of the root entity.") 39 @ApiModelProperty(position = 2, value = "Type of the root entity.")
39 private EntityType rootType; 40 private EntityType rootType;
@@ -59,6 +60,7 @@ public class RelationsSearchParameters { @@ -59,6 +60,7 @@ public class RelationsSearchParameters {
59 this.fetchLastLevelOnly = fetchLastLevelOnly; 60 this.fetchLastLevelOnly = fetchLastLevelOnly;
60 } 61 }
61 62
  63 + @JsonIgnore
62 public EntityId getEntityId() { 64 public EntityId getEntityId() {
63 return EntityIdFactory.getByTypeAndUuid(rootType, rootId); 65 return EntityIdFactory.getByTypeAndUuid(rootType, rootId);
64 } 66 }