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:

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

    • MODEL_NAME_PREFIX_PROPERTY

      public static final String MODEL_NAME_PREFIX_PROPERTY
      Optional literal prefix for every persisted logical @Model name in one application.

      Fluxzero does not insert a separator. For example, prefix billing and Model name Invoice resolve to billingInvoice. Applications that share a Runtime namespace can use this to avoid Model-name collisions. Changing the prefix changes durable Model identity and requires an application-managed data transition.

      See Also:

    • DEFAULT_DELIVERY_GUARANTEE_PROPERTY

      public static final String DEFAULT_DELIVERY_GUARANTEE_PROPERTY
      Application delivery default for outgoing SDK operations. The conventional environment variable is FLUXZERO_PUBLISHING_DEFAULT_GUARANTEE. Values are NONE, SENT, and STORED; an explicit value overrides the SDK major-version default.
      See Also:

    • GRAPH_STRICT_PROPERTY

      public static final String GRAPH_STRICT_PROPERTY
      Requires exact historical values in Graph views instead of using current DOCUMENT-only values when history is unavailable. Environment variable: FLUXZERO_MODEL_GRAPH_STRICT. Defaults to false, independently of fluxzero.defaults.version. Mutations, assertions and replay always remain strict.
      See Also:

    • ASSERT_CURRENT_PROPERTY

      public static final String ASSERT_CURRENT_PROPERTY
      Interceptor input validation override; environment variable FLUXZERO_INTERCEPT_APPLY_ASSERT_CURRENT.
      See Also:

    • COLLECTION_VALUES_PROPERTY

      public static final String COLLECTION_VALUES_PROPERTY
      Annotation-independent search profile; environment variable FLUXZERO_SEARCH_COLLECTION_VALUES.
      See Also:

    • MODEL_ALIAS_TARGETS_PROPERTY

      public static final String MODEL_ALIAS_TARGETS_PROPERTY
      Property-aware Model identity selection override. Requires a Runtime advertising identity selection version 1.
      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
      fluxzero.model.commitPolicy = async_after_handler_await_after_batch      		 Aggregates and independent models using their default commit policy start commits after their handlers and wait for all started commits together at the end of the current message batch. Existing aggregate applications can retain compatibility behavior with fluxzero.aggregate.commitPolicy = sync_after_batch. Independent models use the new behavior regardless of the defaults version and can opt out explicitly.
      >= 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.07.27 fluxzero.tracking.unconfiguredHandlerConsumerMode = perPackage Handlers without an explicit consumer share one generated consumer per exact handler package and message type. Explicit class/package consumers and custom configurations remain more specific.
      >= 2026.08.04 fluxzero.auth.useUserIdMetadata = true AbstractUserProvider writes $system for the system user and User.id() 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.
      >= 2026.09.09 fluxzero.websocket.reconnectBackoff.enabled = true WebSocket reconnects use equal jitter over a capped exponential delay instead of retrying every second. Existing applications can retain the fixed interval with fluxzero.websocket.reconnectBackoff.enabled = false.
      >= 2026.09.10 fluxzero.eventsourcing.maxFetchBytes = 104857600 Aggregate-history pages request at most 100 MiB of serialized event payload. Existing applications can retain count-only pages with fluxzero.eventsourcing.maxFetchBytes = 0.
      >= 2026.09.10 fluxzero.model.automaticRouting = true Commands with one statically unambiguous Model apply and single-Model events use the canonical Model ID as routing fallback. Explicit segments and routing declarations always take precedence. Set the property to false to retain compatibility behavior.
      >= 2026.10.04 fluxzero.interceptApply.assertCurrent = true Validating apply operations also check the input of each selected interceptor before transformation. Set the property to false to preserve replacement-only validation; explicit interceptor overrides win.
      >= 2026.10.09 fluxzero.search.collectionValues = true Ranges use min/max interval overlap; ascending field sorting uses MIN, descending MAX, missing values last. Requires a compatible Runtime; incomplete indexed extrema retain legacy behavior until application reindexing. This fallback includes explicit MIN/MAX. Set false for legacy behavior.
      >= 2026.10.18 fluxzero.model.aliasTargets = true Model mutation ID properties select primary IDs; matching alias properties select canonical owners. Requires Runtime identity-selection version 1. Set false to retain compatibility selection.

      Consumer delivery filtering and fifteen-minute idle reads are enabled automatically on supporting Runtime connections, independently of this date. Override with fluxzero.tracking.consumerFiltering or fluxzero.tracking.maxWaitDuration; unsupported peers retain broad delivery and the historic scan wait.

      Independent Model conflict handling defaults to RETRY for updates and creations regardless of this version. Override it with fluxzero.model.conflictPolicy (FLUXZERO_MODEL_CONFLICT_POLICY) or explicit builder/Model/Apply configuration. Create-only compatibility remains a separate check.

      Outgoing delivery defaults to STORED in SDK 2.x and normally NONE in SDK 1.x, independently of this date. Unconfigured 1.x scheduling clients and cancellation retain SENT. Override it with DEFAULT_DELIVERY_GUARANTEE_PROPERTY. Remote request/reply separately defaults to STORED in SDK 2.x and SENT in SDK 1.x. The same DEFAULT_DELIVERY_GUARANTEE_PROPERTY overrides request/reply; the defaults date has no effect.

      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

    • getRequestDeliveryGuarantee

      public static Guarantee getRequestDeliveryGuarantee(PropertySource propertySource)
      Resolves request/reply delivery from the shared DEFAULT_DELIVERY_GUARANTEE_PROPERTY. Without an override SDK 2.x uses Guarantee.STORED and SDK 1.x retains Guarantee.SENT. The defaults version has no effect. Explicit NONE, SENT and STORED are all honored. Business responses remain independent of publication acknowledgments.
      Parameters:
      propertySource - application-local properties
      Returns:
      a concrete delivery guarantee
      Throws:
      IllegalArgumentException - if an explicit guarantee is invalid

    • getDefaultDeliveryGuarantee

      public static Guarantee getDefaultDeliveryGuarantee(PropertySource propertySource)
      Resolves the application delivery default using the owning component's property source. SDK 2.x uses Guarantee.STORED without an override; SDK 1.x normally uses Guarantee.NONE, retaining stronger legacy operation defaults when unconfigured. This setting is independent of the defaults date. Invalid values, including unresolved DEFAULT, fail.
      Parameters:
      propertySource - application-local properties
      Returns:
      a concrete delivery guarantee

    • graphStrict

      public static boolean graphStrict(PropertySource propertySource)
      Resolves Graph strictness from the application's own property source.

    • assertCurrent

      public static boolean assertCurrent()
      Resolves interceptor input validation from the active application at configuration time.

    • assertCurrent

      public static boolean assertCurrent(PropertySource source)
      Resolves interceptor input validation from the owning application's source at configuration time.

    • collectionValues

      public static boolean collectionValues(PropertySource source)
      Resolves the search profile once from the owning application's property source.

    • modelAliasTargets

      public static boolean modelAliasTargets(PropertySource source)
      Resolves Model identity selection from the owning application's property source.

    • getDefaultsVersion

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

    • getDefaultsVersion

      public static LocalDate getDefaultsVersion(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(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(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(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 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.