Package org.elasticsearch.xpack.esql.datasources.spi

Class DataSourceConfiguration

java.lang.Object
org.elasticsearch.xpack.esql.datasources.spi.DataSourceConfiguration
Direct Known Subclasses:
FileDataSourceConfiguration
public abstract class DataSourceConfiguration extends Object
Base class for datasource configurations. Handles map-backed storage, unknown field rejection, and toStoredSettings(). Subclasses provide cross-field validation via validate(ValidationException).

  • Field Details

    • DEPRECATED_AUTH_MESSAGE

      public static final String DEPRECATED_AUTH_MESSAGE
      Deprecation-warning message template emitted when a deprecated auth value alias is canonicalized on parse. The two {} placeholders are the deprecated value and its canonical replacement, in that order. Shared by every normalize() that canonicalizes an auth alias so the emitted string stays byte-identical across datasource types (a serverless test filters on it).
      See Also:

    • DEPRECATED_AUTH_LOG_KEY_PREFIX

      public static final String DEPRECATED_AUTH_LOG_KEY_PREFIX
      Deprecation-logger key prefix for a deprecated auth value; the deprecated value name is appended to form the per-alias key (e.g. esql_datasource_auth_none). Shared so every normalize() keys the warning identically.
      See Also:

  • Constructor Details

    • DataSourceConfiguration

      protected DataSourceConfiguration(Map<String,Object> raw, Map<String,DataSourceConfigDefinition> fieldDefs)
      Parses, normalizes, and validates raw settings from a REST request or CRUD layer. Rejects unknown fields, then calls subclass validate(ValidationException) for cross-field checks. Values preserve their original types (String, Integer, Boolean, etc.) for non-lossy round-trips. Fields marked caseInsensitive are automatically lowercased on input. All validation errors are accumulated and thrown together.

      Note: validate() is a virtual call during base construction. This is safe because subclasses must not add instance fields — all state is accessed via get(java.lang.String) from the already-populated base class. Subclass constructors should be private.

      Parameters:
      raw - the raw settings map from the REST request
      fieldDefs - the field definitions
      Throws:
      ValidationException - if any validation errors are found

    • DataSourceConfiguration

      protected DataSourceConfiguration(Map<String,Object> raw, Map<String,DataSourceConfigDefinition> fieldDefs, Set<String> preexistingSecretKeys)
      Like DataSourceConfiguration(Map, Map), but for a PUT-as-update: a secret field omitted from raw is still treated as present (see hasStoredSecret(java.lang.String)) if its name is in preexistingSecretKeys, so credential-completeness checks pass when the caller intends to keep the existing value. The caller excludes any key the request explicitly clears (JSON null).
      Parameters:
      preexistingSecretKeys - secret field names already stored, empty for a create

  • Method Details

    • normalize

      protected void normalize(Map<String,Object> parsed)
      Subclass hook to canonicalize parsed values before they are frozen — e.g. mapping a deprecated enum alias to its current value so the stored configuration (and every later read) holds the canonical form. Runs after unknown-field rejection and case-insensitive lowering, before validate(org.elasticsearch.common.ValidationException). The default is a no-op. Like validate(org.elasticsearch.common.ValidationException), this is a virtual call during construction, so overrides must touch only the supplied map and static data, never instance fields.

    • validate

      protected abstract void validate(ValidationException errors)
      Cross-field validation. Accumulate errors into the provided exception.

    • hasAnySecretValue

      protected boolean hasAnySecretValue()
      True if any field marked secret has a value set, or a preexisting one carries forward (see hasStoredSecret(java.lang.String)).

    • hasAnyExplicitSecretValue

      protected boolean hasAnyExplicitSecretValue()
      True if any field marked secret has a value set in this request specifically, excluding any preexisting secret carried forward from a stored value. Use this to distinguish "this request supplied credentials" from "credentials came from the existing entry" in a conflict message — e.g. rejecting auth=anonymous because a stored secret wasn't cleared shouldn't say the request supplied one.

    • hasStoredSecret

      protected boolean hasStoredSecret(String key)
      True if the named secret field has a value set in this request, or carries forward from a preexisting stored value on a PUT-as-update. Use this, not Strings.hasText(get(key)), in hasCredentials()/credential-completeness checks so an update that omits an already-stored secret still satisfies them.

    • hasFederatedAuth

      public boolean hasFederatedAuth()
      Returns true if any field marked as federated identity (aka keyless auth) has a value set. Null values are already excluded.

    • filterKnown

      protected static Configured<Map<String,Object>> filterKnown(Map<String,Object> raw, Map<String,DataSourceConfigDefinition> fieldDefs)
      Returns a copy of raw containing only entries whose key is in fieldDefs, paired with the set of keys that were kept. Used at query time where a query-time configuration map carries a mix of storage and format options; the storage plugin must ignore keys it does not own rather than reject them as unknown. Returns null/empty unchanged.

      Dropped keys are logged at DEBUG so a user who misspells e.g. accout can find out why the storage config came back with defaults. Only key names are logged — values are never emitted, since this method is unaware of which keys are secrets. Format keys (like header_row) will appear here too, which is expected.

    • filterAndConstruct

      protected static <T> Configured<T> filterAndConstruct(Map<String,Object> raw, Map<String,DataSourceConfigDefinition> fieldDefs, Function<Map<String,Object>,T> constructor)
      Filters raw to keys in fieldDefs via filterKnown(java.util.Map<java.lang.String, java.lang.Object>, java.util.Map<java.lang.String, org.elasticsearch.xpack.esql.datasources.spi.DataSourceConfigDefinition>), then constructs a configuration from the kept entries (or null if none kept). Pairs the result with the consumed-keys set. Use from each subclass's fromQueryConfig to eliminate the filter-construct-pair pipeline boilerplate.

    • buildRawMap

      protected static Map<String,Object> buildRawMap(Object... fieldValuePairs)
      Builds a raw settings map from alternating field/value pairs, skipping nulls. Returns null if all values are null. Used by fromFields() factory methods.

    • toMap

      public Map<String,Object> toMap()
      Returns the internal values map. Normalized, no nulls, types preserved.

    • get

      public String get(String key)
      Gets a setting value as a string. Returns toString() of the stored value, or null.

    • toStoredSettings

      public Map<String,DataSourceSetting> toStoredSettings()
      Returns validated settings as a map from field name to DataSourceSetting.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object