Improve some swagger/jdoc around condition updates to better indicate…

… that

the condition set is treated as a whole, and as such any update to the set
results in a new set, ** with new condition ids **.

hawkular-alerts-api/src/main/java/org/hawkular/alerts/api/services/DefinitionsService.java

@@ -162,8 +162,13 @@ Collection<Dampening> getTriggerDampenings(String tenantId, String triggerId, Tr
     /**
      * A convenience method that adds a new Condition to the existing condition set for the specified
      * Trigger and trigger mode.  The new condition will be assigned the highest conditionSetIndex for the
-     * updated conditionSet. The following Condition fields are ignored for the
-     * incoming condition, and set in the returned collection set:<pre>
+     * updated conditionSet.
+     * <p>
+     * IMPORTANT! Add/Delete/Update of a condition effectively replaces the condition set for the trigger.  The new
+     * condition set is returned. Clients code should then use the new condition set as ConditionIds may have changed!
+     * </p>
+     * The following Condition fields are ignored for the incoming condition, and set in the returned collection set:
+     * <pre>
      *   conditionId
      *   triggerId
      *   triggerMode
@@ -181,8 +186,11 @@ Collection<Condition> addCondition(String tenantId, String triggerId, Trigger.Mo
             throws Exception;
 
     /**
-     * A convenience method that removes a Condition from an existing condition set. This will update the
-     * conditionSetSize and possibly the conditionSetIndex for any remaining conditions.
+     * A convenience method that removes a Condition from an existing condition set.
+     * <p>
+     * IMPORTANT! Add/Delete/Update of a condition effectively replaces the condition set for the trigger.  The new
+     * condition set is returned. Clients code should then use the new condition set as ConditionIds may have changed!
+     * </p>
      * @param tenantId Tenant where trigger and his conditions are stored
      * @param conditionId Condition id to be removed
      * @return The updated, persisted condition set. Not null. Can be empty.
@@ -192,6 +200,10 @@ Collection<Condition> addCondition(String tenantId, String triggerId, Trigger.Mo
 
     /**
      * A convenience method that updates an existing Condition from an existing condition set.
+     * <p>
+     * IMPORTANT! Add/Delete/Update of a condition effectively replaces the condition set for the trigger.  The new
+     * condition set is returned. Clients code should then use the new condition set as ConditionIds may have changed!
+     * </p>
      * @param tenantId
      * @param condition Not null. conditionId must be for an existing condition.
      * @return The updated, persisted condition set. Not null. Can be empty.
@@ -201,8 +213,13 @@ Collection<Condition> addCondition(String tenantId, String triggerId, Trigger.Mo
 
     /**
      * The condition set for a trigger's trigger mode is treated as a whole.  When making any change to the
-     * conditions just [re-]set all of the conditions. The following Condition fields are ignored for the
-     * incoming conditions, and set in the returned collection:<pre>
+     * conditions just [re-]set all of the conditions.
+     * <p>
+     * IMPORTANT! Add/Delete/Update of a condition effectively replaces the condition set for the trigger.  The new
+     * condition set is returned. Clients code should then use the new condition set as ConditionIds may have changed!
+     * </p>
+     * The following Condition fields are ignored for the incoming conditions, and set in the returned collection:
+     * <pre>
      *   conditionId
      *   triggerId
      *   triggerMode

hawkular-alerts-rest/src/main/java/org/hawkular/alerts/rest/TriggersHandler.java

@@ -541,7 +541,9 @@ public Response getTriggerCondition(
     @POST
     @Path("/{triggerId}/conditions")
     @Produces(APPLICATION_JSON)
-    @ApiOperation(value = "Create a new condition for a specific trigger")
+    @ApiOperation(value = "Create a new condition for a specific trigger. Add/Delete/Update of a condition "
+            + "effectively replaces the condition set for the trigger.  The new condition set is returned. "
+            + "Clients code should then use the new condition set as ConditionIds may have changed!")
     @ApiResponses(value = {
             @ApiResponse(code = 200, message = "Success, Condition created"),
             @ApiResponse(code = 404, message = "No trigger found"),
@@ -604,7 +606,9 @@ public Response createCondition(
     @PUT
     @Path("/{triggerId}/conditions/{conditionId}")
     @Produces(APPLICATION_JSON)
-    @ApiOperation(value = "Update an existing condition for a specific trigger")
+    @ApiOperation(value = "Update an existing condition for a specific trigger. Add/Delete/Update of a condition "
+            + "effectively replaces the condition set for the trigger.  The new condition set is returned. "
+            + "Clients code should then use the new condition set as ConditionIds may have changed!")
     @ApiResponses(value = {
             @ApiResponse(code = 200, message = "Success, Condition updated"),
             @ApiResponse(code = 404, message = "No Condition found"),
@@ -672,7 +676,9 @@ public Response updateCondition(
     @DELETE
     @Path("/{triggerId}/conditions/{conditionId}")
     @Produces(APPLICATION_JSON)
-    @ApiOperation(value = "Delete an existing condition for a specific trigger")
+    @ApiOperation(value = "Delete an existing condition for a specific trigger. Add/Delete/Update of a condition "
+            + "effectively replaces the condition set for the trigger.  The new condition set is returned. "
+            + "Clients code should then use the new condition set as ConditionIds may have changed!")
     @ApiResponses(value = {
             @ApiResponse(code = 200, message = "Success, Condition deleted"),
             @ApiResponse(code = 404, message = "No Condition found"),
@@ -834,7 +840,7 @@ private boolean isEmpty(String s) {
         return null == s || s.trim().isEmpty();
     }
 
-    private boolean isEmpty(Collection collection) {
-        return collection == null || collection.isEmpty();
-    }
+    //    private boolean isEmpty(Collection collection) {
+    //        return collection == null || collection.isEmpty();
+    //    }
 }