Package com.ssgllc.fish.service.util.registered

Class SystemUtil

java.lang.Object
com.ssgllc.fish.service.util.registered.SystemUtil
@Component public class SystemUtil extends Object
Application-level facts and services: configuration values, text templates, caches, logging, and database capability.

Prefer these over hardcoding anything environment-specific - getBaseUrl(), getEnvironmentName() and getSystemTimezone() keep a script correct in every environment it runs in. getApplicationProperty(String) is deliberately restricted: it serves only the application's own namespaces and withholds anything named like a secret.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SystemUtil(org.springframework.core.env.Environment environment, com.ssgllc.fish.service.cache.EntityConfigCacheService entityConfigCacheService, com.ssgllc.fish.service.cache.CustomCacheService customCacheService, com.ssgllc.fish.config.ApplicationProperties applicationProperties, String springJpaDatabase)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    debug(String message)
    Writes message to the application log at DEBUG level (off in normal operation), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request.
    static void
    error(String message)
    Writes message to the application log at ERROR level (always on), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request.
    static <T> T
    evaluateExpression(Object rootObject, String expression, String returnTypeName, boolean mapContext)
    Evaluate given expression in context of a root object and return result in given type.

    Example:
    evaluateExpression(entity, "firstName == null", "java.lang.Boolean", false)
    Returns:
    Boolean true or false
    static <T> T
    evaluateExpressionSafe(Object rootObject, String expression, String returnTypeName, boolean mapContext, T exceptionReturnValue)
    Safely evaluates a given expression within the context of a specified root object and returns the result cast to the specified type.
    If the evaluation fails due to an exception, a fallback value is returned instead.
    static Object
    executeScript(String templateName, Map<String,Object> config, List<Map<String,Object>> payload, Object body)
    Runs a named TextTemplate as a Groovy script and returns its result.
    static String
    getAppConfig(String name)
    Retrieves the application configuration value associated with the given name.
    static boolean
    getAppConfigBoolean(String name, boolean defaultVal)
    Retrieves the application configuration value associated with the given name as a boolean, or returns the specified default value if the configuration is not found or cannot be parsed as a boolean.
    static Integer
    getAppConfigInteger(String name, Integer defaultVal)
    Retrieves the application configuration value associated with the given name as an integer, or returns the specified default value if the configuration is not found or cannot be parsed as an integer.
    static String
    getAppConfigString(String name, String defaultVal)
    Retrieves the application configuration value associated with the given name, or returns the specified default value if the configuration is not found.
    static String
    getApplicationProperty(String key)
    Reads a Spring environment property, restricted to the application's own namespaces and with secrets withheld.
    static String
    getBaseUrl()
    The application's configured base URL.
    static Object
    getCache(String cacheName)
    Returns a whole named cache, for iterating or inspecting it.
    static String
    getEcPrivateKeyFolder()
    Filesystem folder holding the EC private keys used for signing.
    static String
    getEnvironmentName()
    The application's configured environment name.
    static Object
    getFromCache(String cacheName, String entryKey)
    Reads one entry from a named application cache.
    static String
    getNodeId()
    Identifies the node running this code, as "hostname ipAddress".
    static String
    getSystemTimezone()
    The application's configured system time zone.
    static String
    getTextTemplate(String name)
    The text of a named TextTemplate, read from cache.
    static void
    info(String message)
    Writes message to the application log at INFO level (on in normal operation), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request.
    static Object
    inspect(Object object)
    Logs a value at WARN and returns it unchanged, so it can be dropped into the middle of an expression or a chain without restructuring the code.
    static boolean
    isDebugEnabled()
    Whether DEBUG logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil.
    static boolean
    isErrorEnabled()
    Whether ERROR logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil.
    static boolean
    isInfoEnabled()
    Whether INFO logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil.
    static boolean
    isTraceEnabled()
    Whether TRACE logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil.
    static boolean
    isVectorSupported()
    Whether this deployment's database supports vector columns, which today means PostgreSQL.
    static boolean
    isWarnEnabled()
    Whether WARN logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil.
    static void
    trace(String message)
    Writes message to the application log at TRACE level (the finest level, off in normal operation), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request.
    static void
    warn(String message)
    Writes message to the application log at WARN level (always on), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • SystemUtil

      public SystemUtil(org.springframework.core.env.Environment environment, com.ssgllc.fish.service.cache.EntityConfigCacheService entityConfigCacheService, com.ssgllc.fish.service.cache.CustomCacheService customCacheService, com.ssgllc.fish.config.ApplicationProperties applicationProperties, @Value("${spring.jpa.database}") String springJpaDatabase)

  • Method Details

    • getApplicationProperty

      public static String getApplicationProperty(String key)
      Reads a Spring environment property, restricted to the application's own namespaces and with secrets withheld. Returns null - rather than throwing - for anything outside the allowed prefixes (APPLICATION_, application., CASETIVITY_, casetivity.) and for any key whose name contains password or secret in any case. So a script cannot read arbitrary Spring properties or exfiltrate credentials, and a null means either "not set" or "not readable" - it does not distinguish them.
      Parameters:
      key - the property name, which must start with an allowed prefix
      Returns:
      the property value, or null if unset, out of namespace, or secret-named

      Groovy example:
      return systemUtil.getApplicationProperty("application.baseUrl")
      Returns:
      "https://iis.example.gov"
      SpEL example:
      #getApplicationProperty("application.environmentName")
      Returns:
      "prod"

    • getBaseUrl

      public static String getBaseUrl()
      The application's configured base URL. Use it to build a link that will work in whichever environment the script is running in, rather than hardcoding a host.
      Returns:
      the base URL, e.g. "https://iis.example.gov"

      Groovy example:
      def link = systemUtil.getBaseUrl() + "/#/AppCase/" + entity.id
      Returns:
      a deep link to the case, correct for this environment
      SpEL example:
      #getBaseUrl() + '/#/Order/' + #id
      Returns:
      "https://iis.example.gov/#/Order/3f2b1c8e"

    • getSystemTimezone

      public static String getSystemTimezone()
      The application's configured system time zone. Date functions that need an explicit zone should take it from here rather than from the JVM default, which can differ between nodes.
      Returns:
      the configured zone id, e.g. "America/New_York"

      Groovy example:
      return systemUtil.getSystemTimezone()
      Returns:
      "America/New_York"
      SpEL example:
      #f().instant.of(#createdDate).inZone(#getSystemTimezone()).toIso()
      Returns:
      the creation timestamp rendered in the application's zone

    • getEcPrivateKeyFolder

      public static String getEcPrivateKeyFolder()
      Filesystem folder holding the EC private keys used for signing. Returns the configured path only - it does not read any key material.
      Returns:
      the configured folder path

      Groovy example:
      return systemUtil.getEcPrivateKeyFolder()
      Returns:
      "/opt/casetivity/keys"

    • getEnvironmentName

      public static String getEnvironmentName()
      The application's configured environment name. Use it to branch behaviour that must differ between environments - suppressing an outbound call outside prod, say - instead of keying on a hostname.
      Returns:
      the environment name, e.g. "prod" or "cert"

      Groovy example:
      return systemUtil.getEnvironmentName() == "prod"
      Returns:
      true only in production
      SpEL example:
      #getEnvironmentName() == 'prod'
      Returns:
      true in production

    • getNodeId

      public static String getNodeId()
      Identifies the node running this code, as "hostname ipAddress". Falls back to a random seven-character string when the local host cannot be resolved, so it is stable for the life of a JVM but not guaranteed to be meaningful across restarts. Useful for attributing a log line or a record to one node of a cluster.
      Returns:
      the node identifier

      Groovy example:
      systemUtil.info("Import ran on " + systemUtil.getNodeId())
      Returns:
      nothing; the node id appears in the log line
      SpEL example:
      #getNodeId()
      Returns:
      "app-node-2 10.4.1.17"

    • getAppConfig

      public static String getAppConfig(String name)
      Retrieves the application configuration value associated with the given name.
      Parameters:
      name - The name of the configuration key to retrieve.
      Returns:
      The configuration value as a string, or null if no value is associated with the key.

      Groovy example:
      return systemUtil.getAppConfig("MyConfig")
      Returns:
      "MyConfigValue"
      SpEL example:
      #getAppConfig("MyConfig")
      Returns:
      "MyConfigValue"

    • getAppConfigString

      public static String getAppConfigString(String name, String defaultVal)
      Retrieves the application configuration value associated with the given name, or returns the specified default value if the configuration is not found.
      Parameters:
      name - The name of the configuration key to retrieve.
      defaultVal - The default value to return if no configuration is found for the key.
      Returns:
      The configuration value as a string, or the specified default value if no value is associated with the key.

      Groovy example:
      return systemUtil.getAppConfigString("HeaderDisplayValue", "My Header")
      Returns:
      "My Header"
      SpEL example:
      #getAppConfigString("HeaderDisplayValue", "My Header")
      Returns:
      "My Header"

    • getAppConfigBoolean

      public static boolean getAppConfigBoolean(String name, boolean defaultVal)
      Retrieves the application configuration value associated with the given name as a boolean, or returns the specified default value if the configuration is not found or cannot be parsed as a boolean.
      Parameters:
      name - The name of the configuration key to retrieve.
      defaultVal - The default value to return if no configuration is found for the key or if the value cannot be parsed as a boolean.
      Returns:
      The configuration value as a boolean, or the specified default value.

      Groovy example:
      return systemUtil.getAppConfigBoolean("IsNewFeatureEnabled", false)
      Returns:
      false
      SpEL example:
      #getAppConfigBoolean("IsNewFeatureEnabled", false)
      Returns:
      false

    • getAppConfigInteger

      public static Integer getAppConfigInteger(String name, Integer defaultVal)
      Retrieves the application configuration value associated with the given name as an integer, or returns the specified default value if the configuration is not found or cannot be parsed as an integer.
      Parameters:
      name - The name of the configuration key to retrieve.
      defaultVal - The default value to return if no configuration is found for the key or if the value cannot be parsed as an integer.
      Returns:
      The configuration value as an integer, or the specified default value.

      Groovy example:
      return systemUtil.getAppConfigInteger("MaxBatchSize", 100)
      Returns:
      100
      SpEL example:
      #getAppConfigInteger("MaxBatchSize", 100)
      Returns:
      100

    • getTextTemplate

      public static String getTextTemplate(String name)
      The text of a named TextTemplate, read from cache. Use it to keep a message body, a fragment of SQL or a word list in configuration rather than in a script. To execute a TextTemplate as a script instead of reading it, use executeScript(String, Map, List, Object).
      Parameters:
      name - the TextTemplate's name
      Returns:
      the template text, or null if no template has that name

      Groovy example:
      def body = systemUtil.getTextTemplate("orderConfirmationEmail")
      Returns:
      the template's text
      SpEL example:
      #getTextTemplate('orderConfirmationEmail')
      Returns:
      the template's text

    • getFromCache

      public static Object getFromCache(String cacheName, String entryKey)
      Reads one entry from a named application cache.
      Parameters:
      cacheName - the cache's name
      entryKey - the entry's key
      Returns:
      the cached value, or null if the cache or the entry is absent

      Groovy example:
      def rates = systemUtil.getFromCache("lookupCache", "taxRates")
      Returns:
      the cached value for that key
      SpEL example:
      #getFromCache('lookupCache', 'taxRates')
      Returns:
      the cached value

    • getCache

      public static Object getCache(String cacheName)
      Returns a whole named cache, for iterating or inspecting it. Prefer getFromCache(String, String) when one key is wanted.
      Parameters:
      cacheName - the cache's name
      Returns:
      the cache, or null if no cache has that name

      Groovy example:
      def cache = systemUtil.getCache("lookupCache")
      Returns:
      the cache itself
      SpEL example:
      #getCache('lookupCache')
      Returns:
      the cache itself

    • executeScript

      public static Object executeScript(String templateName, Map<String,Object> config, List<Map<String,Object>> payload, Object body)
      Runs a named TextTemplate as a Groovy script and returns its result. This is how one script calls another: keep shared logic in a TextTemplate and invoke it here, rather than copying it between BPMN script tasks. To read a template's text without executing it, use getTextTemplate(String).
      Parameters:
      templateName - the TextTemplate to execute
      config - configuration values bound into the script
      payload - rows bound into the script
      body - a single value bound into the script
      Returns:
      whatever the script returns

      Groovy example:
      def result = systemUtil.executeScript("computeEligibility", ['strict': true], null, entity)
      Returns:
      whatever computeEligibility returns

    • evaluateExpression

      public static <T> T evaluateExpression(Object rootObject, String expression, String returnTypeName, boolean mapContext) throws ClassNotFoundException
      Evaluate given expression in context of a root object and return result in given type.

      Example:
      evaluateExpression(entity, "firstName == null", "java.lang.Boolean", false)
      Returns:
      Boolean true or false
      Parameters:
      rootObject - object in scope where given expression will be evaluated
      expression - expression to be evaluated
      returnTypeName - fully qualified name of return type from expression evaluation
      mapContext - true if map accessor should be used in evaluation context, false otherwise
      Returns:
      result from expression evaluation
      Throws:
      ClassNotFoundException

    • evaluateExpressionSafe

      public static <T> T evaluateExpressionSafe(Object rootObject, String expression, String returnTypeName, boolean mapContext, T exceptionReturnValue) throws ClassNotFoundException
      Safely evaluates a given expression within the context of a specified root object and returns the result cast to the specified type.
      If the evaluation fails due to an exception, a fallback value is returned instead.
      Parameters:
      rootObject - The object serving as the evaluation context for the expression.
      expression - The expression to evaluate.
      returnTypeName - The fully qualified name of the expected return type.
      mapContext - Indicates whether the evaluation context should treat the rootObject as a map.
      exceptionReturnValue - The value to return if an exception occurs during evaluation.
      Returns:
      The result of the evaluated expression, or exceptionReturnValue if an error occurs.

      Groovy example:
      return systemUtil.evaluateExpressionSafe(entity, "firstName == null", "java.lang.Boolean", false, false)
      Returns:
      true
      SpEL example:
      #evaluateExpressionSafe(entity, "status == 'ACTIVE'", "java.lang.Boolean", false, false)
      Returns:
      true
      Throws:
      ClassNotFoundException

    • trace

      public static void trace(String message)
      Writes message to the application log at TRACE level (the finest level, off in normal operation), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request. Guard an expensive message with isTraceEnabled().
      Parameters:
      message - the line to log

      Groovy example:
      systemUtil.trace("Processing order " + entity.id)
      Returns:
      nothing; the line is written to the log

    • debug

      public static void debug(String message)
      Writes message to the application log at DEBUG level (off in normal operation), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request. Guard an expensive message with isDebugEnabled().
      Parameters:
      message - the line to log

      Groovy example:
      systemUtil.debug("Processing order " + entity.id)
      Returns:
      nothing; the line is written to the log

    • info

      public static void info(String message)
      Writes message to the application log at INFO level (on in normal operation), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request. Guard an expensive message with isInfoEnabled().
      Parameters:
      message - the line to log

      Groovy example:
      systemUtil.info("Processing order " + entity.id)
      Returns:
      nothing; the line is written to the log

    • warn

      public static void warn(String message)
      Writes message to the application log at WARN level (always on), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request. Guard an expensive message with isWarnEnabled().
      Parameters:
      message - the line to log

      Groovy example:
      systemUtil.warn("Processing order " + entity.id)
      Returns:
      nothing; the line is written to the log

    • error

      public static void error(String message)
      Writes message to the application log at ERROR level (always on), under the logger com.ssgllc.fish.service.util.registered.SystemUtil - that is the logger to enable when looking for these lines, and set-debug-logging is the quickest way to do it for one request. Guard an expensive message with isErrorEnabled().
      Parameters:
      message - the line to log

      Groovy example:
      systemUtil.error("Processing order " + entity.id)
      Returns:
      nothing; the line is written to the log

    • isTraceEnabled

      public static boolean isTraceEnabled()
      Whether TRACE logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil. Use it to skip building a message that would be discarded.
      Returns:
      true if the level is enabled

      Groovy example:
      if (systemUtil.isTraceEnabled()) { systemUtil.trace(bpmUtil.serializeObject(['orderId': 42, 'status': 'OPEN'])) }
      Returns:
      true when the level is on, so the serialisation only happens then

    • isDebugEnabled

      public static boolean isDebugEnabled()
      Whether DEBUG logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil. Use it to skip building a message that would be discarded.
      Returns:
      true if the level is enabled

      Groovy example:
      if (systemUtil.isDebugEnabled()) { systemUtil.debug(bpmUtil.serializeObject(['orderId': 42, 'status': 'OPEN'])) }
      Returns:
      true when the level is on, so the serialisation only happens then

    • isInfoEnabled

      public static boolean isInfoEnabled()
      Whether INFO logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil. Use it to skip building a message that would be discarded.
      Returns:
      true if the level is enabled

      Groovy example:
      if (systemUtil.isInfoEnabled()) { systemUtil.info(bpmUtil.serializeObject(['orderId': 42, 'status': 'OPEN'])) }
      Returns:
      true when the level is on, so the serialisation only happens then

    • isWarnEnabled

      public static boolean isWarnEnabled()
      Whether WARN logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil. Use it to skip building a message that would be discarded.
      Returns:
      true if the level is enabled

      Groovy example:
      if (systemUtil.isWarnEnabled()) { systemUtil.warn(bpmUtil.serializeObject(['orderId': 42, 'status': 'OPEN'])) }
      Returns:
      true when the level is on, so the serialisation only happens then

    • isErrorEnabled

      public static boolean isErrorEnabled()
      Whether ERROR logging is currently enabled for com.ssgllc.fish.service.util.registered.SystemUtil. Use it to skip building a message that would be discarded.
      Returns:
      true if the level is enabled

      Groovy example:
      if (systemUtil.isErrorEnabled()) { systemUtil.error(bpmUtil.serializeObject(['orderId': 42, 'status': 'OPEN'])) }
      Returns:
      true when the level is on, so the serialisation only happens then

    • inspect

      public static Object inspect(Object object)
      Logs a value at WARN and returns it unchanged, so it can be dropped into the middle of an expression or a chain without restructuring the code. WARN rather than DEBUG so the line appears without reconfiguring logging - which also means these calls are worth removing once the question is answered. Throws if object is null, since it logs object.toString().
      Parameters:
      object - the value to log
      Returns:
      the same value

      Groovy example:
      def total = systemUtil.inspect(orderItems).sum { it.quantity }
      Returns:
      the collection, having logged it on the way through
      SpEL example:
      #inspect(#lineItems).size()
      Returns:
      the size, having logged the collection

    • isVectorSupported

      public static boolean isVectorSupported()
      Whether this deployment's database supports vector columns, which today means PostgreSQL. Guard embedding and semantic-search work with this so the same configuration can run against a non-PostgreSQL database without failing.
      Returns:
      true when the configured database is PostgreSQL

      Groovy example:
      if (!systemUtil.isVectorSupported()) { return }
      Returns:
      exits early where embeddings cannot be stored
      SpEL example:
      #isVectorSupported()
      Returns:
      true on PostgreSQL