CHANGE 1:
Patch to show API for Alarms in Fault Management.
AlarmsWebResource.java & Alarm.java show what the external REST API for alarms would look like.
See more info at https://wiki.onosproject.org/display/ONOS/Fault+Management
Everything else is very early and work-in-progress/mostly just stubbed out, and not ready for review but all advice welcome.
CHANGE 2:
[ONOS-3203] Update re. comments on FM API draft.
Comments were from Thomas Vachuska regarding https://gerrit.onosproject.org/#/c/6180/
Change-Id: If8d330d1b18b503e89849587e2d4388bf67becc0
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/Alarm.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/Alarm.java
new file mode 100644
index 0000000..765fbfe
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/Alarm.java
@@ -0,0 +1,211 @@
+/*
+ * Copyright 2014-2015 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import org.onosproject.net.DeviceId;
+
+/**
+ * Representation of an Alarm. At a given instant there can be only one alarm
+ * with the same deviceId + description + source combination.
+ */
+public interface Alarm {
+
+ /**
+ * Returns the unique alarm id within this ONOS instance.
+ *
+ * @return alarm identifier
+ */
+ AlarmId id();
+
+ /**
+ * The device to which this alarm is related.
+ *
+ * @return a device id
+ */
+ DeviceId deviceId();
+
+ /**
+ * Returns a description of alarm.
+ * <p>
+ * It may encapsulate Event Type as described by ITU Recommendation X.736
+ * ITU, Quoting https://tools.ietf.org/html/rfc3877 these include: other,
+ * communicationsAlarm, qualityOfServiceAlarm, processingErrorAlarm,
+ * equipmentAlarm, environmentalAlarm, integrityViolation,
+ * operationalViolation, physicalViolation,
+ * securityServiceOrMechanismViolation, timeDomainViolation
+ * <p>
+ * It may encapsulate Probable Cause as described by ITU Recommendation
+ * X.736 ITU, Quoting
+ * https://www.iana.org/assignments/ianaitualarmtc-mib/ianaitualarmtc-mib
+ * these include : aIS, callSetUpFailure, degradedSignal,
+ * farEndReceiverFailure, framingError, and hundreds more constants.
+ * <p>
+ * It may encapsulate a vendor-specific description of the underlying fault.
+ *
+ * @return description of alarm
+ */
+ String description();
+
+ /**
+ * Returns an entity within the context of this alarm's device. It may be
+ * null if deviceId sufficiently identifies the location. As an example, the
+ * source may indicate a port number
+ *
+ * @return source of alarm within the alarm's referenced Device.
+ */
+ AlarmEntityId source();
+
+ /**
+ * Returns the time when raised.
+ *
+ * @return time when raised, in milliseconds since start of epoch
+ */
+ long timeRaised();
+
+ /**
+ * Returns time at which the alarm was updated most recently, due to some
+ * change in the device, or ONOS. If the alarm has been cleared, this is the
+ * time at which the alarm was cleared.
+ *
+ * @return time when last updated, in milliseconds since start of epoch
+ */
+ long timeUpdated();
+
+ /**
+ * Returns the time when cleared. Null indicated no clear time, i.e. the
+ * alarm is still active.
+ *
+ * @return time when cleared, in milliseconds since start of epoch or null
+ * if uncleared.
+ */
+ Long timeCleared();
+
+ /**
+ * Returns the severity. Note, that cleared alarms may have EITHER
+ * SeverityLevel = CLEARED, or may be not present; both scenarios should be
+ * handled.
+ *
+ * @return severity of the alarm
+ */
+ SeverityLevel severity();
+
+ /**
+ * Returns true if alarm is service affecting Note: Whilst X.733 combines
+ * service-affecting state with severity (where severities of critical and
+ * major are deemed service-affecting) ONOS keeps these attributes separate.
+ *
+ * @return whether service affecting (true indicates it is)
+ */
+ boolean serviceAffecting();
+
+ /**
+ * Returns a flag to indicate if this alarm has been acknowledged. All
+ * alarms are unacknowledged until and unless an ONOS user takes action to
+ * indicate so.
+ *
+ * @return whether alarm is currently acknowledged (true indicates it is)
+ */
+ boolean acknowledged();
+
+ /**
+ * Returns a flag to indicate if this alarm is manually-cleared by a user action within ONOS. Some stateless events
+ * e.g. backup-failure or upgrade-failure, may be mapped by ONOS to alarms, and these may be deemed manually-
+ * clearable. The more typical case is that an alarm represents a persistent fault on or related to a device and
+ * such alarms are never manually clearable, i.e. a configuration or operational state must occur for the alarm to
+ * clear.
+ *
+ * @return whether it may be cleared by a user action (true indicates it is)
+ */
+ boolean manuallyClearable();
+
+ /**
+ * Returns the user to whom this alarm is assigned; this is for future use
+ * and always returns null in this release. It is anticipated that in future ONOS
+ * releases, the existing JAAS user/key/role configuration will be extended
+ * to include a mechanism whereby some groups of users may allocate alarms
+ * to other users for bookkeeping and administrative purposes, and that ONOS
+ * will additionally provide a REST based mechanism, to retrieve from JAAS,
+ * the set of users to whom alarm assignment is possible for the current
+ * user.
+ *
+ * @return the assigned user; always null in this release.
+ */
+ String assignedUser();
+
+ /**
+ * Represents the severity level on an alarm, as per ITU-T X.733
+ * specifications.
+ * <p>
+ * The precedence is as follows for : Critical > Major > Minor > Warning.
+ */
+ enum SeverityLevel {
+
+ /**
+ * From X.733: This indicates the clearing of one or more previously
+ * reported alarms. This alarm clears all alarms for this managed object
+ * that have the same Alarm type, Probable cause and Specific problems
+ * (if given). Multiple associated notifications may be cleared by using
+ * the Correlated notifications parameter (defined below). This
+ * Recommendation | International Standard does not require that the
+ * clearing of previously reported alarms be reported. Therefore, a
+ * managing system cannot assume that the absence of an alarm with the
+ * Cleared severity level means that the condition that caused the
+ * generation of previous alarms is still present. Managed object
+ * definers shall state if, and under which conditions, the Cleared
+ * severity level is used.
+ */
+ CLEARED,
+ /**
+ * From X.733: This indicates that the severity level cannot be
+ * determined.
+ */
+ INDETERMINATE,
+ /**
+ * From X.733: This indicates that a service affecting condition has
+ * occurred and an immediate corrective action is required. Such a
+ * severity can be reported, for example, when a managed object becomes
+ * totally out of service and its capability must be restored.
+ */
+ CRITICAL,
+ /**
+ * X.733 definition: This indicates that a service affecting condition
+ * has developed and an urgent corrective action is required. Such a
+ * severity can be reported, for example, when there is a severe
+ * degradation in the capability of the managed object and its full
+ * capability must be restored.
+ */
+ MAJOR,
+ /**
+ * From X.733: This indicates the existence of a non-service affecting
+ * fault condition and that corrective action should be taken in order
+ * to prevent a more serious (for example, service affecting) fault.
+ * Such a severity can be reported, for example, when the detected alarm
+ * condition is not currently degrading the capacity of the managed
+ * object.
+ */
+ MINOR,
+ /**
+ * From X.733: This indicates the detection of a potential or impending
+ * service affecting fault, before any significant effects have been
+ * felt. Action should be taken to further diagnose (if necessary) and
+ * correct the problem in order to prevent it from becoming a more
+ * serious service affecting fault.
+ */
+ WARNING;
+
+ }
+
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmEntityId.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmEntityId.java
new file mode 100644
index 0000000..5bf8674
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmEntityId.java
@@ -0,0 +1,75 @@
+/*
+ * Copyright 2014-2015 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import com.google.common.collect.ImmutableSet;
+import java.net.URI;
+import java.util.Objects;
+import java.util.Set;
+
+/**
+ * Immutable representation of a alarm source. It is meaningful within the
+ * context of a device.
+ */
+public final class AlarmEntityId {
+
+ public static final AlarmEntityId NONE = new AlarmEntityId(URI.create("none:none"));
+ public static final Set<String> SCHEMES = ImmutableSet.of("none", "port", "och", "other");
+
+ private final URI uri;
+
+ private AlarmEntityId(final URI uri) {
+ this.uri = uri;
+ }
+
+ protected AlarmEntityId() {
+ uri = NONE.uri;
+ }
+
+ public static AlarmEntityId alarmEntityId(final String string) {
+ return alarmEntityId(URI.create(string));
+ }
+
+ public static AlarmEntityId alarmEntityId(final URI uri) {
+ checkArgument(SCHEMES.contains(uri.getScheme()), "Unexpected scheme");
+ return new AlarmEntityId(uri);
+ }
+
+ @Override
+ public String toString() {
+ return uri.toString();
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(uri);
+
+ }
+
+ @Override
+ public boolean equals(final Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj instanceof AlarmEntityId) {
+ final AlarmEntityId other = (AlarmEntityId) obj;
+ return Objects.equals(this.uri, other.uri);
+ }
+ return false;
+ }
+
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmEvent.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmEvent.java
new file mode 100644
index 0000000..bbbd993
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmEvent.java
@@ -0,0 +1,65 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import org.onosproject.event.AbstractEvent;
+
+/**
+ * Entity that represents Alarm events.
+ */
+public class AlarmEvent extends AbstractEvent<AlarmEvent.Type, Alarm> {
+
+
+ /**
+ * Creates an event of a given type and for the specified alarm and the
+ * current time.
+ *
+ * @param type topology event type
+ * @param alarm the alarm
+ */
+ public AlarmEvent(Type type, Alarm alarm) {
+ super(type, alarm);
+ }
+
+ /**
+ * Creates an event of a given type and for the specified alarm and time.
+ *
+ * @param type link event type
+ * @param alarm the alarm
+ * @param time occurrence time
+ */
+ public AlarmEvent(Type type, Alarm alarm,
+ long time) {
+ super(type, alarm, time);
+ }
+
+ /**
+ * Type of alarm events.
+ */
+ public enum Type {
+ /**
+ * A Raised Alarm.
+ */
+ RAISE,
+
+ /**
+ * A Cleared Alarm.
+ */
+ CLEAR
+ }
+
+
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmId.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmId.java
new file mode 100644
index 0000000..e0107f8
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmId.java
@@ -0,0 +1,84 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import com.google.common.annotations.Beta;
+
+import java.util.Objects;
+
+import static com.google.common.base.MoreObjects.toStringHelper;
+
+/**
+ * Alarm identifier suitable as an external key.
+ * <p>
+ * This class is immutable.</p>
+ */
+@Beta
+public final class AlarmId {
+
+ private final long id;
+
+ /**
+ * Instantiates a new Alarm id.
+ *
+ * @param id the id
+ */
+ public AlarmId(final long id) {
+ this.id = id;
+ }
+
+ /**
+ * Creates an alarm identifier from the specified long representation.
+ *
+ * @param value long value
+ * @return intent identifier
+ */
+ public static AlarmId valueOf(final long value) {
+ return new AlarmId(value);
+ }
+
+ /**
+ * Returns the backing integer index.
+ *
+ * @return backing integer index
+ */
+ public long fingerprint() {
+ return id;
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(id);
+ }
+
+ @Override
+ public boolean equals(final Object obj) {
+ if (this == obj) {
+ return true;
+ }
+ if (obj instanceof AlarmId) {
+ final AlarmId other = (AlarmId) obj;
+ return Objects.equals(this.id, other.id);
+ }
+ return false;
+ }
+
+ @Override
+ public String toString() {
+ return toStringHelper(this).add("id", id).toString();
+ }
+
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmListener.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmListener.java
new file mode 100644
index 0000000..c5e82ba
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmListener.java
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import org.onosproject.event.EventListener;
+
+
+/**
+ * Entity capable of receiving Alarm related events.
+ */
+public interface AlarmListener extends EventListener<AlarmEvent> {
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProvider.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProvider.java
new file mode 100644
index 0000000..82bcda2
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProvider.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.provider.Provider;
+
+/**
+ * Abstraction of a Alarm provider.
+ */
+public interface AlarmProvider extends Provider {
+
+ /**
+ * Triggers an asynchronous discovery of the alarms on the specified device,
+ * intended to refresh internal alarm model for the device. An indirect
+ * result of this should be invocation of
+ * {@link org.onosproject.incubator.net.faultmanagement.alarm.AlarmProviderService#updateAlarmList} )}
+ * at some later point in time.
+ *
+ * @param deviceId ID of device to be probed
+ */
+ void triggerProbe(DeviceId deviceId);
+
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProviderRegistry.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProviderRegistry.java
new file mode 100644
index 0000000..618298c
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProviderRegistry.java
@@ -0,0 +1,25 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+
+import org.onosproject.net.provider.ProviderRegistry;
+
+/**
+ * Abstraction of a alarm provider registry.
+ */
+public interface AlarmProviderRegistry extends ProviderRegistry<AlarmProvider, AlarmProviderService> {
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProviderService.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProviderService.java
new file mode 100644
index 0000000..727aa28
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmProviderService.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2014 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+
+import org.onosproject.net.DeviceId;
+import org.onosproject.net.provider.ProviderService;
+
+import java.util.Collection;
+
+/**
+ * The interface Alarm provider service.
+ */
+public interface AlarmProviderService extends ProviderService<AlarmProvider> {
+
+ /**
+ * Sends active alarm list for a device.
+ *
+ * @param deviceId identity of the device
+ * @param alarms list of device alarms
+ */
+ void updateAlarmList(DeviceId deviceId, Collection<Alarm> alarms);
+
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmService.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmService.java
new file mode 100644
index 0000000..03c0c7b
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/AlarmService.java
@@ -0,0 +1,121 @@
+/*
+ * Copyright 2014-2015 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import com.google.common.annotations.Beta;
+//import org.onosproject.event.ListenerService;
+
+import java.util.Set;
+import org.onosproject.net.ConnectPoint;
+import org.onosproject.net.DeviceId;
+
+/**
+ * Service for interacting with the alarm handling of devices. Unless stated
+ * otherwise method return active AND recently-cleared alarms.
+ */
+@Beta
+public interface AlarmService {
+// extends ListenerService<AlarmEvent, AlarmListener> {
+
+ /**
+ * Alarm should be updated in ONOS's internal representation; only
+ * administration/book-keeping fields may be updated. Attempting to update
+ * fields which are mapped directly from device is prohibited.
+ *
+ * @param replacement alarm with updated book-keeping fields
+ * @return updated alarm (including any recent device derived changes)
+
+ * @throws java.lang.IllegalStateException if attempt to update not allowed
+ * fields.
+ */
+ Alarm update(Alarm replacement);
+
+ /**
+ * Returns the number of ACTIVE alarms on a device.
+ *
+ * @param deviceId the device
+ * @return number of alarms
+ */
+ int getActiveAlarmCount(DeviceId deviceId);
+
+ /**
+ * Returns the alarm with the specified identifier.
+ *
+ * @param alarmId alarm identifier
+ * @return alarm or null if one with the given identifier is not known
+ */
+ Alarm getAlarm(AlarmId alarmId);
+
+ /**
+ * Returns all of the alarms.
+ *
+ * @return the alarms
+ */
+ Set<Alarm> getAlarms();
+
+ /**
+ * Returns all of the ACTIVE alarms. Recently cleared alarms excluded.
+ *
+ * @return the alarms
+ */
+ Set<Alarm> getActiveAlarms();
+
+ /**
+ * Returns the alarms with the specified severity.
+ *
+ * @param severity the alarm severity
+ * @return the active alarms with a particular severity
+ */
+ Set<Alarm> getAlarms(Alarm.SeverityLevel severity);
+
+ /**
+ * Returns the alarm for a given device, regardless of source within that
+ * device.
+ *
+ * @param deviceId the device
+ * @return the alarms
+ */
+ Set<Alarm> getAlarms(DeviceId deviceId);
+
+ /**
+ * Returns the alarm for a given device and source.
+ *
+ * @param deviceId the device
+ * @param source the source within the device
+ * @return the alarms
+ */
+ Set<Alarm> getAlarms(DeviceId deviceId, AlarmEntityId source);
+
+ /**
+ * Returns the alarm affecting a given link.
+ *
+ * @param src one end of the link
+ * @param dst one end of the link
+ * @return the alarms
+ */
+ Set<Alarm> getAlarmsForLink(ConnectPoint src, ConnectPoint dst);
+
+ /**
+ * Returns the alarm affecting a given flow.
+ *
+ * @param deviceId the device
+ * @param flowId the flow
+ * @return the alarms
+ */
+ Set<Alarm> getAlarmsForFlow(DeviceId deviceId, long flowId);
+
+// Support retrieving alarms affecting other ONOS entity types may be added in future release
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/DefaultAlarm.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/DefaultAlarm.java
new file mode 100644
index 0000000..afa366a
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/DefaultAlarm.java
@@ -0,0 +1,309 @@
+/*
+ * Copyright 2014-2015 Open Networking Laboratory
+ *
+ * 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.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;
+
+import org.onosproject.net.DeviceId;
+
+import java.util.Objects;
+
+import static com.google.common.base.MoreObjects.toStringHelper;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+/**
+ * Default implementation of an alarm.
+ */
+public final class DefaultAlarm implements Alarm {
+
+ private final AlarmId id;
+
+ private final DeviceId deviceId;
+ private final String description;
+ private final AlarmEntityId source;
+ private final long timeRaised;
+ private final long timeUpdated;
+ private final Long timeCleared;
+ private final SeverityLevel severity;
+ private final boolean isServiceAffecting;
+ private final boolean isAcknowledged;
+ private final boolean isManuallyClearable;
+ private final String assignedUser;
+
+ /**
+ * Instantiates a new Default alarm.
+ *
+ * @param id the id
+ * @param deviceId the device id
+ * @param description the description
+ * @param source the source, null indicates none.
+ * @param timeRaised the time raised.
+ * @param timeUpdated the time last updated.
+ * @param timeCleared the time cleared, null indicates uncleared.
+ * @param severity the severity
+ * @param isServiceAffecting the service affecting
+ * @param isAcknowledged the acknowledged
+ * @param isManuallyClearable the manually clearable
+ * @param assignedUser the assigned user, `null` indicates none.
+ */
+ private DefaultAlarm(final AlarmId id,
+ final DeviceId deviceId,
+ final String description,
+ final AlarmEntityId source,
+ final long timeRaised,
+ final long timeUpdated,
+ final Long timeCleared,
+ final SeverityLevel severity,
+ final boolean isServiceAffecting,
+ final boolean isAcknowledged,
+ final boolean isManuallyClearable,
+ final String assignedUser) {
+ this.id = id;
+ this.deviceId = deviceId;
+ this.description = description;
+ this.source = source;
+ this.timeRaised = timeRaised;
+ this.timeUpdated = timeUpdated;
+ this.timeCleared = timeCleared;
+ this.severity = severity;
+ this.isServiceAffecting = isServiceAffecting;
+ this.isAcknowledged = isAcknowledged;
+ this.isManuallyClearable = isManuallyClearable;
+ this.assignedUser = assignedUser;
+ }
+
+ @Override
+ public AlarmId id() {
+ return id;
+ }
+
+ @Override
+ public DeviceId deviceId() {
+ return deviceId;
+ }
+
+ @Override
+ public String description() {
+ return description;
+ }
+
+ @Override
+ public AlarmEntityId source() {
+ return source;
+ }
+
+ @Override
+ public long timeRaised() {
+ return timeRaised;
+ }
+
+ @Override
+ public long timeUpdated() {
+ return timeUpdated;
+ }
+
+ @Override
+ public Long timeCleared() {
+ return timeCleared;
+ }
+
+ @Override
+ public SeverityLevel severity() {
+ return severity;
+ }
+
+ @Override
+ public boolean serviceAffecting() {
+ return isServiceAffecting;
+ }
+
+ @Override
+ public boolean acknowledged() {
+ return isAcknowledged;
+ }
+
+ @Override
+ public boolean manuallyClearable() {
+ return isManuallyClearable;
+ }
+
+ @Override
+ public String assignedUser() {
+ return assignedUser;
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hash(id, deviceId, description,
+ source, timeRaised, timeUpdated, timeCleared, severity,
+ isServiceAffecting, isAcknowledged,
+ isManuallyClearable, assignedUser);
+ }
+
+ @Override
+ public boolean equals(final Object obj) {
+ if (obj == null) {
+ return false;
+ }
+ if (getClass() != obj.getClass()) {
+ return false;
+ }
+ final DefaultAlarm other = (DefaultAlarm) obj;
+ if (!Objects.equals(this.id, other.id)) {
+ return false;
+ }
+ if (!Objects.equals(this.deviceId, other.deviceId)) {
+ return false;
+ }
+ if (!Objects.equals(this.description, other.description)) {
+ return false;
+ }
+ if (!Objects.equals(this.source, other.source)) {
+ return false;
+ }
+ if (this.timeRaised != other.timeRaised) {
+ return false;
+ }
+ if (this.timeUpdated != other.timeUpdated) {
+ return false;
+ }
+ if (!Objects.equals(this.timeCleared, other.timeCleared)) {
+ return false;
+ }
+ if (this.severity != other.severity) {
+ return false;
+ }
+ if (this.isServiceAffecting != other.isServiceAffecting) {
+ return false;
+ }
+ if (this.isAcknowledged != other.isAcknowledged) {
+ return false;
+ }
+ if (this.isManuallyClearable != other.isManuallyClearable) {
+ return false;
+ }
+ if (!Objects.equals(this.assignedUser, other.assignedUser)) {
+ return false;
+ }
+ return true;
+ }
+
+ @Override
+ public String toString() {
+ return toStringHelper(this)
+ .add("id", id)
+ .add("deviceId", deviceId)
+ .add("description", description)
+ .add("source", source)
+ .add("timeRaised", timeRaised)
+ .add("timeUpdated", timeUpdated)
+ .add("timeCleared", timeCleared)
+ .add("severity", severity)
+ .add("serviceAffecting", isServiceAffecting)
+ .add("acknowledged", isAcknowledged)
+ .add("manuallyClearable", isManuallyClearable)
+ .add("assignedUser", assignedUser)
+ .toString();
+ }
+
+ public static class Builder {
+
+ // Manadatory fields ..
+ private final AlarmId id;
+ private final DeviceId deviceId;
+ private final String description;
+ private final SeverityLevel severity;
+ private final long timeRaised;
+
+ // Optional fields ..
+ private AlarmEntityId source = AlarmEntityId.NONE;
+ private long timeUpdated;
+ private Long timeCleared = null;
+ private boolean isServiceAffecting = false;
+ private boolean isAcknowledged = false;
+ private boolean isManuallyClearable = false;
+ private String assignedUser = null;
+
+ public Builder(final Alarm alarm) {
+ this(alarm.id(), alarm.deviceId(), alarm.description(), alarm.severity(), alarm.timeRaised());
+ this.source = AlarmEntityId.NONE;
+ this.timeUpdated = alarm.timeUpdated();
+ this.timeCleared = alarm.timeCleared();
+ this.isServiceAffecting = alarm.serviceAffecting();
+ this.isAcknowledged = alarm.acknowledged();
+ this.isManuallyClearable = alarm.manuallyClearable();
+ this.assignedUser = alarm.assignedUser();
+
+ }
+
+ public Builder(final AlarmId id, final DeviceId deviceId,
+ final String description, final SeverityLevel severity, final long timeRaised) {
+ super();
+ this.id = id;
+ this.deviceId = deviceId;
+ this.description = description;
+ this.severity = severity;
+ this.timeRaised = timeRaised;
+ // Unless specified time-updated is same as raised.
+ this.timeUpdated = timeRaised;
+ }
+
+ public Builder forSource(final AlarmEntityId source) {
+ this.source = source;
+ return this;
+ }
+
+ public Builder withTimeUpdated(final long timeUpdated) {
+ this.timeUpdated = timeUpdated;
+ return this;
+ }
+
+ public Builder withTimeCleared(final Long timeCleared) {
+ this.timeCleared = timeCleared;
+ return this;
+ }
+
+ public Builder withServiceAffecting(final boolean isServiceAffecting) {
+ this.isServiceAffecting = isServiceAffecting;
+ return this;
+ }
+
+ public Builder withAcknowledged(final boolean isAcknowledged) {
+ this.isAcknowledged = isAcknowledged;
+ return this;
+ }
+
+ public Builder withManuallyClearable(final boolean isManuallyClearable) {
+ this.isManuallyClearable = isManuallyClearable;
+ return this;
+ }
+
+ public Builder withAssignedUser(final String assignedUser) {
+ this.assignedUser = assignedUser;
+ return this;
+ }
+
+ public DefaultAlarm build() {
+ checkNotNull(id, "Must specify an alarm id");
+ checkNotNull(deviceId, "Must specify a device");
+ checkNotNull(description, "Must specify a description");
+ checkNotNull(timeRaised, "Must specify a time raised");
+ checkNotNull(timeUpdated, "Must specify a time updated");
+ checkNotNull(severity, "Must specify a severity");
+
+ return new DefaultAlarm(id, deviceId, description, source, timeRaised, timeUpdated, timeCleared,
+ severity, isServiceAffecting, isAcknowledged, isManuallyClearable, assignedUser);
+ }
+ }
+}
diff --git a/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/package-info.java b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/package-info.java
new file mode 100644
index 0000000..b2b8ec9
--- /dev/null
+++ b/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/package-info.java
@@ -0,0 +1,20 @@
+/*
+ * Copyright 2015 Open Networking Laboratory
+ *
+ * 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.
+ */
+/**
+ * Abstractions for interacting with alarms. An alarm is a persistent indication
+ * of a fault that clears only when the triggering condition has been resolved.
+ */
+package org.onosproject.incubator.net.faultmanagement.alarm;