diff options
Diffstat (limited to 'framework/src/onos/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/Alarm.java')
| -rw-r--r-- | framework/src/onos/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/Alarm.java | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/framework/src/onos/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/Alarm.java b/framework/src/onos/incubator/api/src/main/java/org/onosproject/incubator/net/faultmanagement/alarm/Alarm.java new file mode 100644 index 00000000..765fbfef --- /dev/null +++ b/framework/src/onos/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; + + } + +} |