Merge pull request #15 from lucasponce/DOC

Doc

README.adoc

@@ -1,36 +1,151 @@
 = hawkular-alerts
 
-== hawkular-bus
+[.lead]
+*Hawkular Alerts* is the alerts module for Hawkular. It is responsible to define conditions rules over data events
+and fire alerts that can be sent by several notifications plugins.
 
-1. `cd hawkular-bus ; mvn clean install -Pdev`
+Hawkular is a modular systems monitoring suite, that consists of several sub-projects for
+storing of metrics, alerting on incoming events and more. Those projects are developed
+in their own GitHub repositories and integrated in this project.
 
-== hawkular-alerts
+== About Alerts
 
-1. `cd hawkular-alerts ; mvn clean install -Pdev`
+The project is divided into several modules
 
-In case you don't have hawkular-bus and hawkular-alerts project in the same folder you should indicate path of bus:
+[cols=">s,d"]
+|=======================
+| hawkular-alerts-api |
+This is the public Java API for alerts component. +
+Users should use only this API to interact with alerts.
+| hawkular-alerts-engine |
+This is the implementation of the alerts engine. +
+It is responsible to manage the alerts definitions and the evaluation of the alerts conditions. +
+It includes a rules engine as part of the implementation details.
+| hawkular-alerts-rest |
+This is a public REST API for alerts component. +
+It is a wrapper of the main *hawkular-alerts-api*.
+| hawkular-alerts-bus |
+This component is responsible for the communication between the alerts engine and the bus. +
+*hawkular-alerts-engine* is decoupled from the bus, so it can be used in other scenarios +
+(i.e. standalone, third party alerts system).
+| hawkular-notifiers-api |
+Common API for notifiers plugins. +
+A notifier plugin will be deployed as a .war artifact and it will interact with the bus via this API.
+| hawkular-notifiers-email +
+hawkular-notifiers-sms +
+hawkular-notifiers-snmp |
+Project examples with the skeleton of a notifier plugin. +
+Main responsabilities are: +
+- Register at deployment time into the alerts-engine. +
+- Process registration of new notifiers. +
+- Process notifications messages.
+|=======================
 
-1. `NEST_HOME=$PATH_TO/hawkular-bus/hawkular-nest/hawkular-nest-distro/target/wildfly-8.2.0.Final`
-2. `cd hawkular-alerts ; mvn clean install -Pdev -Dorg.hawkular.wildfly.home=$NEST_HOME`
+== Setup
 
-== Test the bus
+Hawkular Alerts can be easily deployed using Hawkular Bus as main container.
 
-1. Send metrics to Hawkular Bus:
+1. Prepare *hawkular-bus* in your local environment
 
-[source]
+```shell
+git clone https://github.com/hawkular/hawkular-bus.git
+cd hawkular-bus
+mvn clean install -Pdev
+```
+
+Profile *-Pdev* creates a pre-configured wildfly-8.2.0.Final server with all dependencies needed in
+
+```shell
+$YOUR_FOLDER/hawkular-bus/hawkular-nest/hawkular-nest-distro/target/wildfly-8.2.0.Final
+```
+
+We will call this wildfly server as *$NEST_HOME*
+
+[start=2]
+2. Prepare *hawkular-alerts* in your local environment
+
+```shell
+git clone https://github.com/hawkular/hawkular-alerts.git
+cd hawkular-alerts
+mvn clean install -Pdev
+```
+
+Profile *-Pdev* copies *hawkular-alerts* artifacts into *$NEST_HOME*. +
+If *hawkular-bus* and *hawkular-alerts* are not in the same folder, you can define the location of wildfly server like:
+
+```shell
+NEST_HOME=$PATH_TO/hawkular-bus/hawkular-nest/hawkular-nest-distro/target/wildfly-8.2.0.Final
+mvn clean install -Pdev -Dorg.hawkular.wildfly.home=$NEST_HOME
+```
+
+[start=3]
+3. Start the nest:
+
+```shell
+cd $NEST_HOME
+bin/standalone.sh
+```
+
+== Integration tests
+
+Once the nest is up and running we can run the integration tests using *-Prest* profile:
+
+```shell
+mvn clean install -Prest
+```
+
+== Documentation
+
+REST API documentation can be generated using *-Pdocgen* profile. +
+The doc is generated under *hawkular-alerts-rest/target* folder.
+
+```shell
+mvn clean install -Pdocgen
+```
+
+== Debug
+
+1. Set a DEBUG logger in the nest:
+
+[source,xml]
 ----
+<logger category="org.hawkular.alerts">
+    <level name="DEBUG"/>
+</logger>
+----
+
+[start=2]
+2. Use curl to send messages directly to the bus for debugging:
+
+```shell
 curl -X POST -H "Content-Type: application/json" \
 --data "{\"data\" : [ { \"id\": \"NumericData-01\", \"type\" : \"numeric\", \"value\" : 0.1} ]}" \
-http://localhost:8080/hawkular-bus/message/MetricsTopic
+http://localhost:8080/hawkular-bus/message/HawkularAlertData
 
 curl -X POST -H "Content-Type: application/json" \
 --data "{\"data\" : [ { \"id\": \"StringData-01\", \"type\" : \"string\", \"value\" : \"Barney\"} ]}" \
-http://localhost:8080/hawkular-bus/message/MetricsTopic
+http://localhost:8080/hawkular-bus/message/HawkularAlertData
 
 curl -X POST -H "Content-Type: application/json" \
 --data "{\"data\" : [ { \"id\": \"Availability-01\", \"type\" : \"availability\", \"value\" : \"UP\"} ]}" \
-http://localhost:8080/hawkular-bus/message/MetricsTopic
+http://localhost:8080/hawkular-bus/message/HawkularAlertData
+```
+
+== License
+
+Hawkular-Alerts is released under Apache License, Version 2.0 as described in the link:LICENSE[LICENSE] document
 
 ----
+   Copyright 2015 Red Hat, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
 
+       http://www.apache.org/licenses/LICENSE-2.0
 
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

hawkular-alerts-rest/pom.xml

@@ -73,6 +73,14 @@
       <scope>provided</scope>
     </dependency>
 
+    <!-- documentation -->
+    <dependency>
+      <groupId>com.wordnik</groupId>
+      <artifactId>swagger-annotations_2.9.1</artifactId>
+      <version>${version.com.swagger}</version>
+      <scope>provided</scope>
+    </dependency>
+
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
@@ -101,14 +109,6 @@
           <scope>test</scope>
         </dependency>
 
-        <!-- documentation -->
-        <dependency>
-          <groupId>com.wordnik</groupId>
-          <artifactId>swagger-annotations_2.9.1</artifactId>
-          <version>${version.com.swagger}</version>
-          <scope>provided</scope>
-        </dependency>
-
       </dependencies>
 
       <build>
@@ -157,7 +157,7 @@
               <proc>only</proc>
               <compilerArguments>
                 <AtargetDirectory>${project.build.directory}/docs/xml</AtargetDirectory>
-                <AmodelPkg>org.hawkular.metrics.restServlet</AmodelPkg>
+                <AmodelPkg>org.hawkular.alerts.rest</AmodelPkg>
                 <!--<AskipPkg>org.rhq.enterprise.server.rest.reporting</AskipPkg> -->
                 <!-- enable the next line to have the output of the processor
                   shown on console -->
@@ -205,7 +205,7 @@
                   <parameters>
                     <parameter>
                       <name>basePath</name>
-                      <value>http://localhost:8080/hawkular-metrics</value>
+                      <value>http://localhost:8080/hawkular/alerts</value>
                     </parameter>
                   </parameters>
                   <outputDir>${project.build.directory}/docs/html</outputDir>
@@ -228,7 +228,7 @@
                   <parameters>
                     <parameter>
                       <name>basePath</name>
-                      <value>http://localhost:8080/hawkular-metrics</value>
+                      <value>http://localhost:8080/hawkular/alerts</value>
                     </parameter>
                   </parameters>
                   <outputDir>${project.build.directory}/docs/html</outputDir>
@@ -255,7 +255,7 @@
                   <parameters>
                     <parameter>
                       <name>basePath</name>
-                      <value>http://localhost:8080/hawkular-metrics</value>
+                      <value>http://localhost:8080/hawkular/alerts</value>
                     </parameter>
                   </parameters>
                   <outputDir>${project.build.directory}/docs/xml</outputDir>

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

@@ -16,6 +16,8 @@
  */
 package org.hawkular.alerts.rest;
 
+import com.wordnik.swagger.annotations.Api;
+import com.wordnik.swagger.annotations.ApiOperation;
 import org.hawkular.alerts.api.model.condition.Alert;
 import org.hawkular.alerts.api.services.AlertsService;
 import org.hawkular.alerts.rest.log.MsgLogger;
@@ -41,6 +43,7 @@
  * @author Lucas Ponce
  */
 @Path("/")
+@Api(value = "/", description = "Operations about alerts")
 public class AlertsHandler {
     private final MsgLogger msgLog = MsgLogger.LOGGER;
     private final Logger log = Logger.getLogger(AlertsHandler.class);
@@ -55,6 +58,9 @@ public AlertsHandler() {
     @GET
     @Path("/")
     @Produces(APPLICATION_JSON)
+    @ApiOperation(value = "Find all alerts",
+                  responseClass = "Collection<org.hawkular.alerts.api.model.condition.Alert>",
+                  notes = "Pagination is not yet implemented.")
     public void findAllAlerts(@Suspended final AsyncResponse response) {
         Collection<Alert> alertList = alerts.checkAlerts();
         if (alertList.isEmpty()) {
@@ -68,6 +74,10 @@ public void findAllAlerts(@Suspended final AsyncResponse response) {
 
     @GET
     @Path("/reload")
+    @ApiOperation(value = "Reload all definitions into the alerts service",
+                  responseClass = "void",
+                  notes = "This service is temporal for demos/poc, this functionality will be handled internally" +
+                          "between definitions and alerts services")
     public void reloadAlerts(@Suspended final AsyncResponse response) {
         alerts.reload();
         response.resume(Response.status(Response.Status.OK).build());

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

@@ -16,6 +16,9 @@
  */
 package org.hawkular.alerts.rest;
 
+import com.wordnik.swagger.annotations.Api;
+import com.wordnik.swagger.annotations.ApiOperation;
+import com.wordnik.swagger.annotations.ApiParam;
 import org.hawkular.alerts.api.model.condition.AvailabilityCondition;
 import org.hawkular.alerts.api.model.condition.Condition;
 import org.hawkular.alerts.api.services.DefinitionsService;
@@ -48,6 +51,8 @@
  * @author Lucas Ponce
  */
 @Path("/conditions/availability")
+@Api(value = "/conditions/availability",
+     description = "Create/Read/Update/Delete operations for AvailabilityCondition type condition")
 public class AvailabilityConditionsHandler {
     private final Logger log = Logger.getLogger(AvailabilityConditionsHandler.class);
 
@@ -61,6 +66,9 @@ public AvailabilityConditionsHandler() {
     @GET
     @Path("/")
     @Produces(APPLICATION_JSON)
+    @ApiOperation(value = "Find all availability conditions",
+                  responseClass = "Collection<org.hawkular.alerts.api.model.condition.AvailabilityCondition>",
+                  notes = "Pagination is not yet implemented")
     public void findAllAvailabilityConditions(@Suspended final AsyncResponse response) {
         try {
             Collection<Condition> conditionsList = definitions.getConditions();
@@ -89,11 +97,54 @@ public void findAllAvailabilityConditions(@Suspended final AsyncResponse respons
         }
     }
 
+    @GET
+    @Path("/trigger/{triggerId}")
+    @Produces(APPLICATION_JSON)
+    @ApiOperation(value = "Find all availability conditions for a specific trigger",
+                  responseClass = "Collection<org.hawkular.alerts.api.model.condition.AvailabilityCondition>",
+                  notes = "Pagination is not yet implemented")
+    public void findAllAvailabilityConditionsByTrigger(@Suspended final AsyncResponse response,
+                                                       @ApiParam(value = "Trigger id to get availability conditions",
+                                                                 required = true)
+                                                       @PathParam("triggerId") final String triggerId) {
+        try {
+            Collection<Condition> conditionsList = definitions.getConditions(triggerId);
+            Collection<AvailabilityCondition> availabilityConditions = new ArrayList<AvailabilityCondition>();
+            for (Condition cond : conditionsList) {
+                if (cond instanceof AvailabilityCondition) {
+                    availabilityConditions.add((AvailabilityCondition) cond);
+                }
+            }
+            if (availabilityConditions.isEmpty()) {
+                log.debugf("GET - findAllAvailabilityConditions - Empty");
+                response.resume(Response.status(Response.Status.NO_CONTENT).type(APPLICATION_JSON_TYPE).build());
+            } else {
+                log.debugf("GET - findAllAvailabilityConditions - %s availability conditions ",
+                           availabilityConditions.size());
+
+                response.resume(Response.status(Response.Status.OK)
+                                        .entity(availabilityConditions).type(APPLICATION_JSON_TYPE).build());
+            }
+        } catch (Exception e) {
+            log.debugf(e.getMessage(), e);
+            Map<String, String> errors = new HashMap<String, String>();
+            errors.put("errorMsg", "Internal Error: " + e.getMessage());
+            response.resume(Response.status(Response.Status.INTERNAL_SERVER_ERROR)
+                                    .entity(errors).type(APPLICATION_JSON_TYPE).build());
+        }
+    }
+
     @POST
     @Path("/")
     @Consumes(APPLICATION_JSON)
     @Produces(APPLICATION_JSON)
+    @ApiOperation(value = "Create a new availability condition",
+                  responseClass = "org.hawkular.alerts.api.model.condition.AvailabilityCondition",
+                  notes = "Returns AvailabilityCondition created if operation finished correctly")
     public void createAvailabilityCondition(@Suspended final AsyncResponse response,
+                                            @ApiParam(value = "Availability condition to be created",
+                                                      name = "condition",
+                                                      required = true)
                                             final AvailabilityCondition condition) {
         try {
             if (condition != null && condition.getConditionId() != null
@@ -121,7 +172,11 @@ public void createAvailabilityCondition(@Suspended final AsyncResponse response,
     @GET
     @Path("/{conditionId}")
     @Produces(APPLICATION_JSON)
+    @ApiOperation(value = "Get an existing availability condition",
+                  responseClass = "org.hawkular.alerts.api.model.condition.AvailabilityCondition")
     public void getAvailabilityCondition(@Suspended final AsyncResponse response,
+                                         @ApiParam(value = "Availability condition id to be retrieved",
+                                                   required = true)
                                          @PathParam("conditionId") final String conditionId) {
         try {
             AvailabilityCondition found = null;
@@ -156,8 +211,15 @@ public void getAvailabilityCondition(@Suspended final AsyncResponse response,
     @PUT
     @Path("/{conditionId}")
     @Consumes(APPLICATION_JSON)
+    @ApiOperation(value = "Update an existing availability condition",
+                  responseClass = "void")
     public void updateAvailabilityCondition(@Suspended final AsyncResponse response,
+                                            @ApiParam(value = "Availability condition id to be updated",
+                                                      required = true)
                                             @PathParam("conditionId") final String conditionId,
+                                            @ApiParam(value = "Updated availability condition",
+                                                      name = "condition",
+                                                      required = true)
                                             final AvailabilityCondition condition) {
         try {
             if (conditionId != null && !conditionId.isEmpty() &&
@@ -185,7 +247,11 @@ public void updateAvailabilityCondition(@Suspended final AsyncResponse response,
 
     @DELETE
     @Path("/{conditionId}")
+    @ApiOperation(value = "Delete an existing availability condition",
+                  responseClass = "void")
     public void deleteAvailabilityCondition(@Suspended final AsyncResponse response,
+                                            @ApiParam(value = "Availability condition id to be deleted",
+                                                      required = true)
                                             @PathParam("conditionId") final String conditionId) {
         try {
             if (conditionId != null && !conditionId.isEmpty() && definitions.getCondition(conditionId) != null) {