Class ApplicationProperties

java.lang.Object
io.fluxzero.sdk.configuration.ApplicationProperties
public class ApplicationProperties extends Object
Central utility for resolving configuration properties within a Fluxzero application.

This class delegates to a layered PropertySource, typically obtained from the active Fluxzero instance. If no context-bound property source is present, it falls back to a DecryptingPropertySource that wraps the default layered DefaultPropertySource.

Property sources are accessed in a prioritized order:

  1. EnvironmentVariablesSource – highest precedence
  2. SystemPropertiesSource
  3. FluxzeroAdditionalPropertiesSource – extra locations declared with FLUXZERO_CONFIG_LOCATIONS
  4. ApplicationEnvironmentPropertiesSource – e.g. application-dev.properties
  5. ApplicationPropertiesSource – fallback base configuration from application.properties
  6. FluxzeroPropertiesSource – Fluxzero-specific SDK defaults from fluxzero.properties or fluxzero.json

Property resolution supports typed access, default values, encryption, and template substitution.

Common usage: 

String token = ApplicationProperties.getProperty("FLUXZERO_API_TOKEN");
boolean featureEnabled = ApplicationProperties.getBooleanProperty("my.feature.enabled", true);
See Also:
  • PropertySource
  • DefaultPropertySource
  • DecryptingPropertySource

  • Field Details

    • TASK_ID_PROPERTY

      public static final String TASK_ID_PROPERTY
      Identity of the platform task that hosts the application. The default environment-variable name is FLUXZERO_TASK_ID; FLUX_TASK_ID remains supported as a legacy alias.
      See Also:

    • LEGACY_TASK_ID_PROPERTY

      public static final String LEGACY_TASK_ID_PROPERTY
      Legacy alias for TASK_ID_PROPERTY.
      See Also:

    • CLIENT_ID_PROPERTY

      public static final String CLIENT_ID_PROPERTY
      Optional explicit unique client-instance ID. The default environment-variable name is FLUXZERO_CLIENT_ID; FLUX_CLIENT_ID remains supported as a legacy alias.
      See Also:

    • LEGACY_CLIENT_ID_PROPERTY

      public static final String LEGACY_CLIENT_ID_PROPERTY
      Legacy alias for CLIENT_ID_PROPERTY.
      See Also:

    • APPLICATION_VERSION_PROPERTY

      public static final String APPLICATION_VERSION_PROPERTY
      Optional version of the deployed application. When configured, Fluxzero adds the value to the correlation metadata of every outgoing message under $applicationVersion. The default environment-variable alias is FLUXZERO_APPLICATION_VERSION.
      See Also:

    • DEFAULTS_VERSION_PROPERTY

      public static final String DEFAULTS_VERSION_PROPERTY
      Selects the versioned Fluxzero default behavior profile for applications that do not configure each default explicitly.

      Existing applications can omit this property to keep compatibility defaults. New applications can set a value in yyyy.MM.dd format to opt into all default changes introduced on or before that date. Each default can still be overridden by its own dedicated property.

      Versioned defaults
      Defaults version Equivalent property Behavior
      >= 2026.05.20 fluxzero.tracking.unconfiguredHandlerConsumerMode = perHandler Handlers without an explicit consumer get an isolated generated default consumer per handler class, instead of joining the shared application default consumer for the message type.
      >= 2026.05.21 fluxzero.scheduling.periodic.useDefaultInitialDelay = true @Periodic schedules without an explicit initialDelay use their natural first deadline: fixed-delay schedules first run after delay, and cron schedules first run at the next cron match. Use initialDelay = 0 for an immediate first run.
      >= 2026.05.25 fluxzero.cache.mode = adaptive The default aggregate cache uses a count-bounded hard-reference cache. Applications can keep the old behavior with fluxzero.cache.mode = softRef. Tracking caches are not changed by this defaults version and require an explicit fluxzero.tracking.cache.mode setting.
      >= 2026.06.09 fluxzero.aggregate.commitPolicy = async_after_handler_await_after_batch Aggregates using the default commit policy start their commits after each handler, keep active thread-local aggregates visible until batch completion, and wait for all started commits together at the end of the current message batch. Existing applications can keep the legacy behavior with fluxzero.aggregate.commitPolicy = sync_after_batch.
      >= 2026.06.20 fluxzero.tracking.defaultHandlingMode.webrequest = async Web request handlers assigned through default consumers are invoked on worker threads by default. Existing applications can keep synchronous handling with fluxzero.tracking.defaultHandlingMode.webrequest = sync or by configuring the web request default consumer with handlingMode = SYNC.
      >= 2026.08.04 fluxzero.auth.useUserIdMetadata = true AbstractUserProvider writes $system for the system user and Principal.getName() for regular users. It resolves $system to the system user and other values through getUserById. Existing applications can keep serialized user objects with fluxzero.auth.useUserIdMetadata = false.
      >= 2026.08.26 fluxzero.web.defaultRedirectPolicy = SAME_ORIGIN Outbound web requests using RedirectPolicy.DEFAULT only follow redirects within the original scheme, host, and effective port. Existing applications can retain normal JDK redirects with fluxzero.web.defaultRedirectPolicy = ALLOW; NEVER disables redirects explicitly.

      Memory-aware cache pressure can be tuned with fluxzero.cache.memoryPressure.heapThresholdPercent, fluxzero.cache.memoryPressure.gcTimeThresholdPercent, and fluxzero.cache.memoryPressure.trimRatioPercent. The amount evicted in a single pass is also capped by fluxzero.cache.memoryPressure.maxTrimWeight.

      See Also:

  • Constructor Details

    • ApplicationProperties

      public ApplicationProperties()

  • Method Details

    • getDefaultsVersion

      public static LocalDate getDefaultsVersion()
      Returns the active Fluxzero defaults version, or null when compatibility defaults are used.

    • getDefaultsVersion

      public static LocalDate getDefaultsVersion(io.fluxzero.common.application.PropertySource propertySource)
      Returns the Fluxzero defaults version from the given source, or null when compatibility defaults are used.
      Throws:
      IllegalArgumentException - if DEFAULTS_VERSION_PROPERTY is not in yyyy.MM.dd format

    • defaultsVersionAtLeast

      public static boolean defaultsVersionAtLeast(LocalDate version)
      Returns whether the active defaults version opts into behavior introduced on or before the given date.

    • defaultsVersionAtLeast

      public static boolean defaultsVersionAtLeast(io.fluxzero.common.application.PropertySource propertySource, LocalDate version)
      Returns whether the given source opts into behavior introduced on or before the given date.

    • getProperty

      public static String getProperty(String name)
      Returns the raw string property for the given key, or null if not found.

    • mapProperty

      public static <T> T mapProperty(String name, Function<String,T> mapper)
      Maps a property value identified by its name to a desired type using the provided mapping function. If the property is not available, the method returns null.

    • mapProperty

      public static <T> T mapProperty(String name, Function<String,T> mapper, Supplier<T> defaultValueSupplier)
      Maps a property value identified by its name to a desired type using the provided mapping function. If the property is not found, the method returns a default value supplied by the given supplier.

    • getFirstAvailableProperty

      public static String getFirstAvailableProperty(String... propertyNames)
      Returns an Optional containing the first non-null property value among the provided property names, if any exist. If no properties are resolved, returns an empty Optional.

    • getTaskId

      public static String getTaskId()
      Returns the configured platform task ID, or null when the application does not run as a known task.

    • getTaskId

      public static String getTaskId(io.fluxzero.common.application.PropertySource propertySource)
      Returns the platform task ID from the given property source, or null when absent or blank.

    • createClientId

      public static String createClientId()
      Creates a unique ID for a client instance. An explicitly configured FLUXZERO_CLIENT_ID is used when present. Otherwise, a random UUID is generated and prefixed with FLUXZERO_TASK_ID when available. Callers should create this ID once and retain it across reconnects.

    • createClientId

      public static String createClientId(io.fluxzero.common.application.PropertySource propertySource)
      Creates a unique ID for a client instance from the given property source.

    • getBooleanProperty

      public static boolean getBooleanProperty(String name)
      Resolves a boolean property by key, returning false if not present.

      Accepts case-insensitive "true" as true, otherwise returns false.

    • getBooleanProperty

      public static boolean getBooleanProperty(String name, boolean defaultValue)
      Resolves a boolean property by key, returning a default if the property is not present.

    • getIntegerProperty

      public static Integer getIntegerProperty(String name)
      Resolves an integer property by key, or null if not found.
      Throws:
      NumberFormatException - if the property value is not a valid integer

    • getIntegerProperty

      public static Integer getIntegerProperty(String name, Integer defaultValue)
      Resolves an integer property by key, or returns the given default value if not found.
      Throws:
      NumberFormatException - if the property value is not a valid integer

    • getLongProperty

      public static Long getLongProperty(String name)
      Resolves a long property by key, or null if not found.
      Throws:
      NumberFormatException - if the property value is not a valid long

    • getLongProperty

      public static Long getLongProperty(String name, Long defaultValue)
      Resolves a long property by key, or returns the given default value if not found.
      Throws:
      NumberFormatException - if the property value is not a valid long

    • getProperty

      public static String getProperty(String name, String defaultValue)
      Returns the string property value for the given key, or the specified default if not found.

    • requireProperty

      public static String requireProperty(String name)
      Returns the string property for the given key, throwing an IllegalStateException if not found.

    • containsProperty

      public static boolean containsProperty(String name)
      Returns true if a property with the given name exists.

    • substituteProperties

      public static String substituteProperties(String template)
      Substitutes placeholders in the given template using current property values.

      Placeholders use the syntax ${propertyName}.

    • substituteProperties

      public static Properties substituteProperties(Properties properties)
      Substitutes placeholders in the properties using current property values.

      Placeholders use the syntax ${propertyName}.

    • getEncryption

      public static io.fluxzero.common.encryption.Encryption getEncryption()
      Returns the currently active Encryption instance.

      By default, wraps the encryption from the current PropertySource.

    • encryptValue

      public static String encryptValue(String value)
      Encrypts the given value using the configured Encryption strategy.

    • decryptValue

      public static String decryptValue(String encryptedValue)
      Decrypts the given encrypted value using the configured Encryption strategy.

      Returns the original value if decryption is not applicable.