Package com.inductiveautomation.ignition.common.model.values

Class QualityCode

  • All Implemented Interfaces:
    java.io.Serializable
    public final class QualityCode
extends java.lang.Object
implements java.io.Serializable
    QualityCode contains a 32-bit integer code and optionally a diagnostic string.

    The 32-bits are arranged as follows: First two bits represent the level 

       0b00 GOOD
   0b01 UNCERTAIN
   0b10 BAD
   0b11 RESERVED

    The next 14 bits are reserved, and NOT CURRENTLY USED.

    The lower 16 bits represent the meaning of the code.

    Inductive Automation reserves the first 1024 codes(0x0000 through 0x03FF) for codes that it will define. By convention, our codes are broken up into four bands within the range of 0 through 1023.

    • Values 0-255 are "good" codes.
    • Values 256-511 are "uncertain" codes
    • Values 512 - 767 are "bad" codes that represent a condition that should have been expected (something didn't work in a way that was entirely predictable, like a device was not connected)
    • Values 768 - 1023 are "worse" bad quality and represent an unambiguous error state - something must be changed.

    Third parties may use codes 1024 through 65535 (0x0400 through 0xFFFF) for their own codes, although doing so will tend to cause very generic "good / bad" representations of the quality.

    The (optional) diagnosticMessage field in this class is used to add contextual information about the circumstance in which the quality code was generated. It is NOT meant to be the name or description of the quality code. In many cases, only the code will be stored / transferred for efficiency, and the diagnostic message may be lost in the long term (e.g. if the code is stored as part of tag history)

    See Also:
    Serialized Form

    • Field Detail

      • Good_Unspecified

        public static final QualityCode Good_Unspecified
        General quality for good data.

      • Good_WritePending

        public static final QualityCode Good_WritePending
        Special value used when an underlying data source is being written to.

      • Good

        public static final QualityCode Good
        This is the standard good value in the Ignition code base, but continues to use the legacy 192 user code. The Good_Unspecified quality code with subcode 0 would be the "modern" base good value.

      • Good_Provisional

        public static final QualityCode Good_Provisional
        Good data that should not be considered valid long-term. Do not cache. We make it a bigger user code than "Good" so that worstOf considers it worse...

      • Good_Initial

        public static final QualityCode Good_Initial
        Special flag simply indicates that this is an initial/seed value for a system just starting up.

      • Good_Overload

        public static final QualityCode Good_Overload
        Good data that is being sampled slower than requested due to resource limitations.

      • Good_Backfill

        public static final QualityCode Good_Backfill
        Used to indicate good quality values that have arrived out of order. Different systems can choose to process them accordingly.

      • Uncertain

        public static final QualityCode Uncertain
        An unspecified degree of uncertainty exists in this value. Good luck!

      • Uncertain_LastKnownValue

        public static final QualityCode Uncertain_LastKnownValue
        The current value is unavailable, this represents the last known good value.

      • Uncertain_InitialValue

        public static final QualityCode Uncertain_InitialValue
        Used to indicate that a subscription has been made and a good value should be arriving shortly.

      • Uncertain_DataSubNormal

        public static final QualityCode Uncertain_DataSubNormal
        Insufficient good-quality sources required for the derivation of this value.

      • Uncertain_EngineeringUnitsExceeded

        public static final QualityCode Uncertain_EngineeringUnitsExceeded
        Used to indicate that a value has gone beyond its configured engineering units.

      • Uncertain_IncompleteOperation

        public static final QualityCode Uncertain_IncompleteOperation
        An asynchronous operation is currently pending and its result is unknown.

      • Bad

        public static final QualityCode Bad
        General quality for a bad value.

      • Bad_Unauthorized

        public static final QualityCode Bad_Unauthorized
        An unauthorized request was made for data that requires authorization.

      • Bad_AccessDenied

        public static final QualityCode Bad_AccessDenied
        Data requested requires credentials not held by requesting user.

      • Bad_Disabled

        public static final QualityCode Bad_Disabled
        Data source is not currently enabled.

      • Bad_Stale

        public static final QualityCode Bad_Stale
        Data is out-of-date based upon the requested refresh interval.

      • Bad_TrialExpired

        public static final QualityCode Bad_TrialExpired
        The trial mode's timer has expired.

      • Bad_LicenseExceeded

        public static final QualityCode Bad_LicenseExceeded
        A license limit has been exceeded.

      • Bad_NotFound

        public static final QualityCode Bad_NotFound
        Object requested was not found.

      • Bad_ReferenceNotFound

        public static final QualityCode Bad_ReferenceNotFound
        Derived or referenced value required an object which was not found.

      • Bad_AggregateNotFound

        public static final QualityCode Bad_AggregateNotFound
        Requested aggregate was not found.

      • Bad_NotConnected

        public static final QualityCode Bad_NotConnected
        A connection required for this value is not currently connected.

      • Bad_GatewayCommOff

        public static final QualityCode Bad_GatewayCommOff
        Connection to the Ignition gateway is currently turned off.

      • Bad_OutOfRange

        public static final QualityCode Bad_OutOfRange
        This value has exceeded its allowed range.

      • Bad_DatabaseNotConnected

        public static final QualityCode Bad_DatabaseNotConnected
        A database connection required for this value is not connected.

      • Bad_ReadOnly

        public static final QualityCode Bad_ReadOnly
        A write was attempted on a read only target.

      • Bad_Failure

        public static final QualityCode Bad_Failure
        A "failure" code was received from the underlying system. Additional details may be in the diagnostic message. This generally doesn't not indicate an exception, which would be handled by Error_Exception, but instead a simple failure from a system that can return success or failure.

      • Bad_Unsupported

        public static final QualityCode Bad_Unsupported
        The operation is not supported by the target.

      • Error

        public static final QualityCode Error
        An unexpected error occurred while retrieving or calculating this value.

      • Error_Configuration

        public static final QualityCode Error_Configuration
        The source of this value is not configured correctly.

      • Error_ExpressionEval

        public static final QualityCode Error_ExpressionEval
        The source expression was unable to be executed.

      • Error_TagExecution

        public static final QualityCode Error_TagExecution
        The source tag could not be executed.

      • Error_TypeConversion

        public static final QualityCode Error_TypeConversion
        The actual value was not able to be coerced into the configured data type for the source of this value.

      • Error_DatabaseQuery

        public static final QualityCode Error_DatabaseQuery
        A database query required for this value caused an error upon execution.

      • Error_IO

        public static final QualityCode Error_IO
        An input/output error occurred while attempting to retrieve or calculate this value.

      • Error_TimeoutExpired

        public static final QualityCode Error_TimeoutExpired
        An asynchronous operation failed due to a timeout.

      • Error_Exception

        public static final QualityCode Error_Exception
        An exception was caught, and logged in the relevant system.

      • Error_InvalidPathSyntax

        public static final QualityCode Error_InvalidPathSyntax
        A path (tag path, property path, etc) was not able to be parsed because the syntax is invalid.

      • Error_Formatting

        public static final QualityCode Error_Formatting
        Attempted formatting (numeric, date formatting) failed.

      • Error_ScriptEval

        public static final QualityCode Error_ScriptEval
        A script needed to create this value failed to execute.

      • Error_CycleDetected

        public static final QualityCode Error_CycleDetected
        Calculating the value involved an execution cycle.

    • Constructor Detail

      • QualityCode

        public QualityCode​(QualityCode.Level level,
                   int userCode,
                   java.lang.String diagnosticMessage)

      • QualityCode

        public QualityCode​(QualityCode copy)

      • QualityCode

        public QualityCode​(QualityCode copy,
                   java.lang.String diagnosticMessage)

      • QualityCode

        public QualityCode​(int code)

      • QualityCode

        public QualityCode​(int code,
                   java.lang.String diagnosticMessage)

    • Method Detail

      • getCode

        public int getCode()

      • getDiagnosticMessage

        @Nullable
public java.lang.String getDiagnosticMessage()
        Returns:
        the diagnostic message associated with this quality, if present. Otherwise, null.

      • isGood

        public boolean isGood()
        Returns:
        true if this code represents a good quality

      • isUncertain

        public boolean isUncertain()
        Returns:
        true if this code is uncertain level (but _not_ bad or error)

      • isBad

        public boolean isBad()
        Returns:
        true if this code is bad level (but _not_ error or uncertain)

      • isError

        public boolean isError()
        Returns:
        true if this code is error level (but _not_ bad or uncertain)

      • isNotGood

        public boolean isNotGood()
        Returns:
        true if this code is uncertain, bad, or error

      • isBadOrError

        public boolean isBadOrError()
        Returns:
        true if this code is bad or error

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getCodeName

        public static java.lang.String getCodeName​(int code)
        Returns:
        the name of the given code, if known. Otherwise, returns the code's severity and its numeric value.

      • getCodeName

        public static java.lang.String getCodeName​(QualityCode code)
        Returns:
        the name of the given code, if known. Otherwise, returns the code's severity and its numeric value.

      • getCodesJson

        public static com.inductiveautomation.ignition.common.gson.JsonObject getCodesJson()
        Returns:
        a JSON object whose keys are code numbers and whose values are the code names

      • derive

        public QualityCode derive​(java.lang.String diagnosticMessage)
        Returns a QualityCode with the same underlying code, but the specified diagnosticMessage.
        Parameters:
        diagnosticMessage - the diagnostic message.
        Returns:
        a QualityCode with the same underlying code, but the specified diagnosticMessage.

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • is

        public boolean is​(QualityCode other)
        Helper function that compares the integer code of the given quality to this one.

      • isNot

        public boolean isNot​(QualityCode other)
        Helper function that compares the integer code of the given quality to this one.

      • getName

        public java.lang.String getName()
        Returns:
        the name of the given code, if known. Otherwise, returns the code's severity and its numeric value.

      • getQualityFor

        public static QualityCode getQualityFor​(java.lang.String name)

      • getQualityFromUserCode

        public static QualityCode getQualityFromUserCode​(int code)

      • getQualityFor

        public static QualityCode getQualityFor​(int code)

      • toValue

        public QualifiedValue toValue()
        Returns this quality as the quality component of a qualified value.