| /* |
| * 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; |
| |
| } |
| |
| } |