Interface PromptServiceHandlerMixin_JsonConfig<ConnectionConfig, QueryConfig>

Type Parameters:
ConnectionConfig - The type of the connection configuration model used by this prompt service.
QueryConfig - The type of the query configuration model used by this prompt service.
All Superinterfaces:
IPromptServiceHandler<ConnectionConfig, QueryConfig>
public interface PromptServiceHandlerMixin_JsonConfig<ConnectionConfig, QueryConfig> extends IPromptServiceHandler<ConnectionConfig, QueryConfig>
Mixin interface for IPromptServiceHandler implementations that provides JSON marshalling for the prompt connection and query configuration. This mixin implements The model class instance is converted to JSON by reading the instance fields and writing them to a JSON object. You should keep your model as a simple data (POJO) object to avoid issues with serialization and deserialization. Also, your model must either have a public no-arg constructor, or you must override newEmptyConnectionConfig() and newEmptyQueryConfig().

You should also implement the getConnectionConfigVersion() and getQueryConfigVersion() in an appropriate manner. Then you can increment the version when you make changes to the model class that are incompatible with the previous serialized data. The updateConnectionConfig and updateQueryConfig methods let you update the serialized data before it gets deserialized into the model class.

If needed, you can override preProcessConnectionConfig and preProcessQueryConfig to modify the model instance before it gets serialized. Similarly, you can override postProcessConnectionConfig and postProcessQueryConfig to modify the model instance after it has been deserialized. One use case for pre-processing is to enforce constraints on the model data that cannot be expressed with the type system. You must always expect data to be deserialized that originates from a different version or prompt type, as users can freely switch between different prompt types.

The exact details of the serialization and deserialization process are unspecified, but you may rely on the following guarantees:

  • Transient fields are excluded from serialization and deserialization.
  • Fields that are missing in the serialized JSON will be set to their default values during deserialization, e.g. as if a new instance was created using the no-arg constructor.
  • Fields in the JSON that do not correspond to any field in the model class will be ignored during deserialization. Such fields will be set to their default value (null).
  • Fields whose type cannot be deserialized from the given data will be ignored during deserialization. E.g. when a field is of type List<String>, but the JSON data contains an object. Such fields will be set to their default value (null).
  • The basic types Boolean, Number, String, Enum, List, Map are supported, as well as nested POJOs that follow the same conventions. In addition, the following types are supported as well:
    • Classes from java.time
  • Fields can be annotated with PromptConfigJsonField to customize the serialization and deserialization process.
  • Discriminated unions are supported via the PromptConfigJsonDiscriminatedUnion annotation, see there for details regarding usage.
  • When deserializing a syntactically invalid JSON string (or deserialization results in an otherwise unhandled error), a default configuration instance will be used (see newEmptyConnectionConfig() / newEmptyQueryConfig()).
  • The text data of the SerializedPromptConfig will contain an entry with the key "json" and the value being a list with a single string element that contains the serialized JSON representation of the model instance.
  • Binary data can be stored by using the PromptConfigFile class. The field type may be either a single PromptConfigFile or a List<PromptConfigFile>. During serialization, this data will be written to the binary data of the SerializedPromptConfig (using the field name as the file key). During deserialization, the binary data will be read from there.
  • The text data of the SerializedPromptConfig will also contain an entry with the key "version" and the value being a list with a single string element that contains the version of the configuration class. The version is taken from getConnectionConfigVersion() / getQueryConfigVersion().
Since:
8.5.0

  • Method Details

    • deserializeConnectionConfig

      default ConnectionConfig deserializeConnectionConfig(SerializedPromptConfig serializedConfig)
      Description copied from interface: IPromptServiceHandler
      Deserializes a serialized prompt connection configuration into a Object object, as previously serialized by IPromptServiceHandler.serializeConnectionConfig(Object). This method allows you to use a custom serialization format, such as JSON or XML.

      Note: There is no guarantee that the serialized data matches the format you expect. The data may come from a different version of the prompt type service, or from a different prompt type service altogether. You must take the necessary precautions to validate the data and handle errors gracefully. In general, we recommend using the data that can be mapped to your model class, discarding the remaining data, and using defaults for missing data.

      It is recommended, but not required, to store the version of the implementation in the serialized configuration. This allows you to update the configuration in this method when newer versions of the implementation require a different configuration format.

      Specified by:
      deserializeConnectionConfig in interface IPromptServiceHandler<ConnectionConfig, QueryConfig>
      Parameters:
      serializedConfig - The serialized configuration to deserialize.
      Returns:
      A deserialized connection configuration object.
      See Also:

    • deserializeQueryConfig

      default QueryConfig deserializeQueryConfig(SerializedPromptConfig serialized)
      Description copied from interface: IPromptServiceHandler
      Deserializes a serialized prompt query configuration into a QueryConfig object, as previously serialized by IPromptServiceHandler.serializeQueryConfig(Object). This method allows you to use a custom serialization format, such as JSON or XML.

      Note: There is no guarantee that the serialized data matches the format you expect. The data may come from a different version of the prompt type service, or from a different prompt type service altogether. You must take the necessary precautions to validate the data and handle errors gracefully. In general, we recommend using the data that can be mapped to your model class, discarding the remaining data, and using defaults for missing data.

      It is recommended, but not required, to store the version of the implementation in the serialized configuration. This allows you to update the configuration in this method when newer versions of the implementation require a different configuration format.

      Specified by:
      deserializeQueryConfig in interface IPromptServiceHandler<ConnectionConfig, QueryConfig>
      Parameters:
      serialized - The serialized configuration to deserialize.
      Returns:
      A deserialized query configuration object.
      See Also:

    • getConnectionConfigVersion

      default String getConnectionConfigVersion()
      Gets the version of the connection configuration class. This is saved in the serialized data. Can be used to update the data if the class definition has undergone changes. If you need to update the serialized data, override the updateConnectionConfig method. Defaults to the serialVersionUID static field of the class, if it exists, or "1.0" otherwise.
      Returns:
      The version of the connection configuration class, as a string.

    • getQueryConfigVersion

      default String getQueryConfigVersion()
      Gets the version of the query configuration class. This is saved in the serialized data. Can be used to update the data if the class definition has undergone changes. If you need to update the serialized data, override the updateQueryConfig method. Defaults to the serialVersionUID static field of the class, if it exists, or "1.0" otherwise.
      Returns:
      The version of the query configuration class, as a string.

    • newEmptyConnectionConfig

      default ConnectionConfig newEmptyConnectionConfig()

    • newEmptyQueryConfig

      default QueryConfig newEmptyQueryConfig()

    • postProcessConnectionConfig

      default ConnectionConfig postProcessConnectionConfig(ConnectionConfig connectionConfig)
      Called after the connection configuration has been deserialized, allowing you to modify the instance before it gets used. The default implementation returns the given instance unchanged.
      Parameters:
      connectionConfig - The deserialized connection configuration.
      Returns:
      The (possibly modified) connection configuration.

    • postProcessQueryConfig

      default QueryConfig postProcessQueryConfig(QueryConfig queryConfig)
      Called after the query configuration has been deserialized, allowing you to modify the instance before it gets used. The default implementation returns the given instance unchanged.
      Parameters:
      queryConfig - The deserialized query configuration.
      Returns:
      The (possibly modified) query configuration.

    • preProcessConnectionConfig

      default ConnectionConfig preProcessConnectionConfig(ConnectionConfig connectionConfig)
      Called before the connection configuration gets serialized, allowing you to adjust or modify the instance before the actual serialization takes place. The default implementation returns the given instance unchanged.
      Parameters:
      connectionConfig - The connection configuration to be serialized.
      Returns:
      The (possibly modified) connection configuration.

    • preProcessQueryConfig

      default QueryConfig preProcessQueryConfig(QueryConfig queryConfig)
      Called before the query configuration gets serialized, allowing you to adjust or modify the instance before the actual serialization takes place. The default implementation returns the given instance unchanged.
      Parameters:
      queryConfig - The query configuration to be serialized.
      Returns:
      The (possibly modified) query configuration.

    • serializeConnectionConfig

      default SerializedPromptConfig serializeConnectionConfig(ConnectionConfig connectionConfig)
      Description copied from interface: IPromptServiceHandler
      Serializes the configuration of a prompt connection into a format that can be stored in a data storage, such as a database or a file. This method allows you to use a custom serialization format, such as JSON or XML.

      It is recommended, but not required, to store the version of the implementation in the serialized configuration. This allows you to update the configuration upon serialization when newer versions of the implementation require a different configuration format.

      Note regarding files: You need to ensure the last modified date is set correctly in the serialized configuration. When saving a prompt connection and the date remains the same, the binary data will not be updated (to avoid reading the data into memory, then writing it back, which is unnecessary). If you change the binary data, you must update the last modified date.

      Specified by:
      serializeConnectionConfig in interface IPromptServiceHandler<ConnectionConfig, QueryConfig>
      Parameters:
      connectionConfig - The configuration of the prompt connection to serialize.
      Returns:
      A serialized representation of the connection configuration, which can be stored in a database or file.
      See Also:

    • serializeQueryConfig

      default SerializedPromptConfig serializeQueryConfig(QueryConfig config)
      Description copied from interface: IPromptServiceHandler
      Serializes the configuration of a prompt query into a format that can be stored in a data storage, such as a database or a file. This method allows you to use a custom serialization format, such as JSON or XML.

      It is recommended, but not required, to store the version of the implementation in the serialized configuration. This allows you to update the configuration upon serialization when newer versions of the implementation require a different configuration format.

      Note regarding files: You need to ensure the last modified date is set correctly in the serialized configuration. When saving a prompt query and the date remains the same, the binary data will not be updated (to avoid reading the data into memory, then writing it back, which is unnecessary). If you change the binary data, you must update the last modified date.

      Specified by:
      serializeQueryConfig in interface IPromptServiceHandler<ConnectionConfig, QueryConfig>
      Parameters:
      config - The configuration of the prompt query to serialize.
      Returns:
      A serialized representation of the query configuration, which can be stored in a database or file.
      See Also:

    • updateConnectionConfig

      default SerializedPromptConfig updateConnectionConfig(SerializedPromptConfig config, String storedVersion, String currentVersion)
      Updates the serialized prompt connection before it gets deserialized into the model. Called only when the current version is different from the current version. Can be used to update the serialized data if the class definition has undergone changes. Note that SerializedPromptConfig is immutable, if you wish to make changes, you must call SerializedPromptConfig.derive(), then apply your changes, and return the new instance.
      Parameters:
      config - The serialized prompt connection configuration to update.
      storedVersion - The version of the configuration stored in the serialized data.
      currentVersion - The current version of the configuration class.

    • updateQueryConfig

      default SerializedPromptConfig updateQueryConfig(SerializedPromptConfig config, String storedVersion, String currentVersion)
      Updates the serialized prompt query configuration before it gets deserialized into the model. Called only when the current version is different from the current version. Can be used to update the serialized data if the class definition has undergone changes. Note that SerializedPromptConfig is immutable, if you wish to make changes, you must call SerializedPromptConfig.derive(), then apply your changes, and return the new instance.
      Parameters:
      config - The serialized prompt query configuration to update.
      storedVersion - The version of the configuration stored in the serialized data.
      currentVersion - The current version of the configuration class.