Merge pull request #67 from jshaughn/hwkalerts-47

HWKALERTS-47 Add Rest query for triggers by tag

hawkular-alerts-api/src/main/java/org/hawkular/alerts/api/model/trigger/Tag.java

@@ -17,7 +17,8 @@
 package org.hawkular.alerts.api.model.trigger;
 
 /**
- * Each instance is a tag
+ * A Trigger can have zero or more Tags.  For storing a Tag the specified Trigger must exist for the specified Tenant
+ * and <code>name</code> is required.
  *
  * @author jay shaughnessy
  * @author lucas ponce
@@ -35,17 +36,13 @@ public Tag() {
     }
 
     /**
-     * Create a searchable Tag on name only
-     *
      * @param name NotEmpty
      */
     public Tag(String name) {
         this(null, null, name, false);
     }
 
     /**
-     * Create a searchable Tag on category + name
-     *
      * @param category Nullable
      * @param name NotEmpty
      */
@@ -54,9 +51,7 @@ public Tag(String category, String name) {
     }
 
     /**
-     * Create an invisible Tag for persisting.
-     *
-     * @param triggerId Nullable Note, required for storage but not search.
+     * @param triggerId Nullable
      * @param category Nullable
      * @param name NotEmpty
      */
@@ -65,7 +60,7 @@ public Tag(String triggerId, String category, String name) {
     }
 
     /**
-     * @param triggerId Nullable Note, required for storage but not search.
+     * @param triggerId Nullable
      * @param category Nullable
      * @param name NotEmpty
      * @param visible flag indicating whether this tag is available for display

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

@@ -85,15 +85,25 @@ public interface DefinitionsService {
      */
     Collection<Trigger> getTriggers(String tenantId) throws Exception;
 
+    /**
+     * Get all stored Triggers with a specific Tag. Category and Name can not both be null.
+     * @param tenantId Tenant where trigger is stored
+     * @param category The tag category, if null or empty fetch only by tag name
+     * @param name The tag name, if null or empty fetch only by tag category
+     * @throws Exception on any problem
+     */
+    Collection<Trigger> getTriggersByTag(String tenantId, String category, String name) throws Exception;
+
     /**
      * Get all stored Triggers for all Tenants
      * @throws Exception on any problem
      */
     Collection<Trigger> getAllTriggers() throws Exception;
 
     /**
-     * Get all stored Triggers for all Tenants with a specific Tag
-     * @param category The tag category, ignored if null
+     * Get all stored Triggers for all Tenants with a specific Tag. This can be inefficient, especially if
+     * querying by name only.
+     * @param category The tag category, if null or empty fetch only by tag name
      * @param name The tag name, required
      * @throws Exception on any problem
      */
@@ -366,9 +376,10 @@ void updateAction(String tenantId, String actionPlugin, String actionId, Map<Str
     */
 
     /**
-     * Add Tag with the specified name to the specified Trigger. Category is optional. If the Tag exists the
-     * call returns successfully but has no effect.
-     * @param tenantId Tenant where tag is stored
+     * Add Tag to the specified Trigger (tenantId+triggerid). Category is optional but highly recommended for
+     * efficiency and to avoid unwanted name collisions. If the Tag exists the call returns successfully but
+     * has no effect.
+     * @param tenantId Tenant where tag is created
      * @param tag New tag to be created
      * @throws Exception on any problem
      */
@@ -384,6 +395,7 @@ void updateAction(String tenantId, String actionPlugin, String actionId, Map<Str
     void removeTags(String tenantId, String triggerId, String category, String name) throws Exception;
 
     /**
+     * @param tenantId NotEmpty, must be the proper tenant for the specified trigger.
      * @param triggerId NotEmpty
      * @param category Nullable.
      * @return The existing Tags for the trigger, optionally filtered by category. Sorted by category, name.