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

Class QualityCode

java.lang.Object
com.inductiveautomation.ignition.common.model.values.QualityCode
All Implemented Interfaces:
Serializable
public final class QualityCode extends Object implements 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:

  • Field Details

    • 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 Details

    • QualityCode

      public QualityCode(QualityCode.Level level, int userCode)

    • QualityCode

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

    • QualityCode

      public QualityCode(QualityCode copy)

    • QualityCode

      public QualityCode(QualityCode copy, String diagnosticMessage)

    • QualityCode

      public QualityCode(int code)

    • QualityCode

      public QualityCode(int code, String diagnosticMessage)

  • Method Details

    • getCode

      public int getCode()

    • getDiagnosticMessage

      @Nullable public 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 String toString()
      Overrides:
      toString in class Object

    • getLevel

      public QualityCode.Level getLevel()

    • getLevel

      public static QualityCode.Level getLevel(int code)

    • getLevel

      public static QualityCode.Level getLevel(QualityCode code)

    • getCodeName

      public static 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 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

    • worstOf

      public static QualityCode worstOf(QualityCode a, QualityCode b)

    • worstOfAll

      public static QualityCode worstOfAll(QualityCode... q)

    • derive

      public QualityCode derive(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(Object obj)
      Overrides:
      equals in class 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 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(String name)

    • getQualityFromUserCode

      public static QualityCode getQualityFromUserCode(int code)

    • getQualityFor

      public static QualityCode getQualityFor(int code)

    • values

      public static QualityCode[] values()

    • toValue

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