com.seeq.message.SeeqMessage.kt Maven / Gradle / Ivy
package com.seeq.message
/** A pattern for structured text messages. Instead of passing around generic strings to show users,
* this enables more structure, deferring the creation of the display message until it's actually needed.
*
* Benefits:
* 1. consistency of text formatting
* 2. retain details for structured logging
* 3. a unique identifier that can be used for logging
* 4. a unique identifier lookup more troubleshooting information in the knowledge base
* 5. maybe assist with i18n tasks
*
* Subsystems will implement one of these for each message, so this interface is very generic in order to avoid
* becoming a hotspot.
*
* Best Practices:
*
* * Each subsystem should encode the message number into an Enum, giving an easy way to find references,
* rather than hard coded numbers.
* * Each subsystem can reserve blocks of unique numbers in the [SeeqMessageNumbers].
* * The message strings should be constructed on get, not on instantiation of the object. We want the assembly
* of message objects to be as fast as possible, since the messages might never be displayed.
* * Do not try to encode additional information into the numbers (e.g. Http 1xx vs 5xx values). The number should
* not imply behavior (exceptions, debug logs) or source of the message (metadata, runtime, operators).
*/
interface SeeqMessage {
/** A globally unique identifier for this message. */
val messageNumber: Int
/** The user-facing message, assembled from member fields. */
val message: String
/** Optional pointer to more information about this particular message.*/
val knowledgeBase: SeeqKnowledgeBase?
/** The message number formatted for displaying to the user and in documentation. */
val messageId: String get() = "SQ-$messageNumber"
}
/** Identify a page in the knowledge base. A micro-type that encapsulates the attributes of the KB. */
data class SeeqKnowledgeBase(val identifier: String)