Class QualityCode
- java.lang.Object
-
- com.inductiveautomation.ignition.common.model.values.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 Values 768 - 1023 are "worse" bad codes that represent a condition that was unexpected
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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
QualityCode.Level
-
Field Summary
Fields Modifier and Type Field Description static QualityCode
Bad
General quality for a bad value.static QualityCode
Bad_AccessDenied
Data requested requires credentials not held by requesting userstatic QualityCode
Bad_AggregateNotFound
Requested aggregate was not foundstatic QualityCode
Bad_DatabaseNotConnected
A database connection required for this value is not connectedstatic QualityCode
Bad_Disabled
Data source is not currently enabled.static QualityCode
Bad_Failure
A "failure" code was received from the underlying system.static QualityCode
Bad_GatewayCommOff
Connection to the Ignition gateway is currently turned offstatic QualityCode
Bad_LicenseExceeded
A license limit has been exceededstatic QualityCode
Bad_NotConnected
A connection required for this value is not currently connectedstatic QualityCode
Bad_NotFound
Object requested was not foundstatic QualityCode
Bad_OutOfRange
This value has exceeded it's allowed rangestatic QualityCode
Bad_ReadOnly
The target is not writable/readonly.static QualityCode
Bad_ReferenceNotFound
Derived or referenced value required an object which was not foundstatic QualityCode
Bad_Stale
Data is out-of-date based upon the requested refresh intervalstatic QualityCode
Bad_TrialExpired
The trial mode's timer has expired.static QualityCode
Bad_Unauthorized
An un-authorized request was made for data that requires authorization.static QualityCode
Bad_Unsupported
The operation is not supported by the target.static QualityCode
Error
An unexpected error occurred while retrieving or calculating this valuestatic QualityCode
Error_Configuration
The source of this value is not configured correctlystatic QualityCode
Error_CycleDetected
Calculating the value involved an execution cycle.static QualityCode
Error_DatabaseQuery
A database query required for this value caused an error upon executionstatic QualityCode
Error_Exception
An exception was caught, and logged in the relevant system.static QualityCode
Error_ExpressionEval
The source expression was unable to be executedstatic QualityCode
Error_Formatting
Attempted formatting (numeric, date formatting) failed.static QualityCode
Error_InvalidPathSyntax
A path (tag path, property path, etc) was not able to be parsed because the syntax is invalid.static QualityCode
Error_IO
An input/output error occurred while attempting to retrieve or calculate this valuestatic QualityCode
Error_ScriptEval
A script needed to create this value failed to executestatic QualityCode
Error_TagExecution
The source tag could not be executedstatic QualityCode
Error_TimeoutExpired
An async operation failed due to a timeout.static QualityCode
Error_TypeConversion
The actual value was not able to be coerced into the configured data type for the source of this valuestatic QualityCode
Good
This is the standard good value in the Ignition code base, but continues to use the legacy 192 user code.static QualityCode
Good_Provisional
Good data that should not be considered valid long-term.static QualityCode
Good_Unspecified
General quality for good datastatic QualityCode
Good_WritePending
Special value used when an underlying data source is being written tostatic QualityCode
Uncertain
An unspecified degree of uncertainty exists in this value.static QualityCode
Uncertain_DataSubNormal
Insufficient good-quality sources required for the derivation of this valuestatic QualityCode
Uncertain_EngineeringUnitsExceeded
Used to indicate that a value has gone beyond its configured engineering units.static QualityCode
Uncertain_IncompleteOperation
An async operation is currently pending and its result is unknown.static QualityCode
Uncertain_InitialValue
Used to indicate that a subscription has been made and a good value should be arriving shortly.static QualityCode
Uncertain_LastKnownValue
The current value is unavailable, this represents the last known good value.
-
Constructor Summary
Constructors Constructor Description QualityCode(int code)
QualityCode(int code, java.lang.String diagnosticMessage)
QualityCode(QualityCode copy)
QualityCode(QualityCode.Level level, int userCode)
QualityCode(QualityCode.Level level, int userCode, java.lang.String diagnosticMessage)
QualityCode(QualityCode copy, java.lang.String diagnosticMessage)
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description QualityCode
derive(java.lang.String diagnosticMessage)
Returns a QualityCode with the same underlying code, but the specifieddiagnosticMessage
.boolean
equals(java.lang.Object obj)
int
getCode()
static java.lang.String
getCodeName(int code)
static java.lang.String
getCodeName(QualityCode code)
static com.inductiveautomation.ignition.common.gson.JsonObject
getCodesJson()
java.lang.String
getDiagnosticMessage()
QualityCode.Level
getLevel()
static QualityCode.Level
getLevel(int code)
static QualityCode.Level
getLevel(QualityCode code)
java.lang.String
getName()
static QualityCode
getQualityFor(int code)
static QualityCode
getQualityFor(java.lang.String name)
boolean
is(QualityCode other)
Helper function that compares the integer code of the given quality to this one.boolean
isBad()
boolean
isBadOrError()
boolean
isError()
boolean
isGood()
boolean
isNot(QualityCode other)
Helper function that compares the integer code of the given quality to this one.boolean
isNotGood()
boolean
isUncertain()
java.lang.String
toString()
QualifiedValue
toValue()
Returns this quality as the quality component of a qualified value.static QualityCode[]
values()
static QualityCode
worstOf(QualityCode a, QualityCode b)
static QualityCode
worstOfAll(QualityCode... q)
-
-
-
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...
-
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 async 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 un-authorized 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 it's 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
The target is not writable/readonly.
-
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 async 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)
-
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 classjava.lang.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 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
-
worstOf
public static QualityCode worstOf(QualityCode a, QualityCode b)
-
worstOfAll
public static QualityCode worstOfAll(QualityCode... q)
-
derive
public QualityCode derive(java.lang.String diagnosticMessage)
Returns a QualityCode with the same underlying code, but the specifieddiagnosticMessage
.- 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 classjava.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)
-
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.
-
-