Package space.arim.dazzleconf.backend

Interface Backend.Meta

Enclosing interface:
Backend
public static interface Backend.Meta
Defines metadata about a backend.

For callers familiar with the java.sql module, this type is analogous to JDBC's DatabaseMetaData. It provides information about the backend implementation itself, such as its supported capabilities.

New methods may be added to this interface in the future, but they will always be default methods. Implementors of Backend are encouraged to keep up-to-date with this interface by checking minor version release notes.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    allKeysAreStrings()
    Whether the backend only recognizes string keys.
    boolean
    preservesOrder(boolean reading)
    Whether this backend supports preservation of data entry order.
    boolean
    supportsComments(boolean documentLevel, boolean reading, @NonNull CommentLocation location)
    Whether comments are supported in the following context.
    boolean
    writesFloatAsDouble()
    Whether the backend writes float values by casting them to double.

  • Method Details

    • supportsComments

      boolean supportsComments(boolean documentLevel, boolean reading, @NonNull CommentLocation location)
      Whether comments are supported in the following context.

      The context is defined by whether the comments are placed on the document level or on specific entries, if the comments are being read or written, and where the comments are located with respect to entries. For example, documentLevel = true, false, and ABOVE specifies the writability of the document-level header, and documentLevel = false, true, and INLINE specify the capability to read inline comments on entries. The return value would then indicate whether comments are handled in this context.

      Implications

      If comments are not supported in this context, this format backend is free to ignore them during Backend.write(Document).

      If this method returns true for reading = true and reading = false with otherwise identical documentLevel and location, that implies that comments in such context will be correctly read -- and identically reconstituted -- by read provided they were written by write.

      Ignored comments during reading

      Note that some backends may expose comments in other places, not covered by this library. An example would be comments on list entries - because the API only supports comments on map entries. These comments are impossible to return from a call to read, meaning they are necessarily produced by the end user. Such kind of comments should have no bearing on this method's results.

      Parameters:
      documentLevel - true for the document level, false for entry-level comments
      reading - true for reading comments, false for writing them
      location - the location of the comments for whom support is queried
      Returns:
      if the backend supports comments in this context

    • preservesOrder

      boolean preservesOrder(boolean reading)
      Whether this backend supports preservation of data entry order.

      The reading parameter defines where ordering happens. If ordering is preserved when reading, this method should return true when reading = true, and if ordering is preserved when writing, it should return true when writing = true.

      Implications

      If order is not preserved during reading, entries in a data tree may be read in any order. If not preserved during writing, the serialized format may be written in a different order.

      If order is preserved in both contexts, then the backend should preserve a stable iteration order across multiple calls to read and write using the same data. Loading a data tree should produce an order which remains stable if that same tree is written and re-read at a later point.

      Parameters:
      reading - true for reading data, false for writing it
      Returns:
      if order is preserved across the reading or writing operation

    • writesFloatAsDouble

      boolean writesFloatAsDouble()
      Whether the backend writes float values by casting them to double.

      Some backend formats do not inherently support floats, but the Backend implementation is required to write them if they appear.

      Implications

      If this method returns true, the Backend will write float values by first casting them to doubles. Conversion operations may lead to a loss of precision in some cases.

      Returns:
      if the backend writes float as doubles

    • allKeysAreStrings

      boolean allKeysAreStrings()
      Whether the backend only recognizes string keys.

      Some backend formats do not support non-string keys, meaning that all keys (no matter what type they appear to be) will be loaded as strings.

      Implications

      If this method returns true, all keys in a loaded DataTree will be strings. During writing, if a non-string key is encountered, the Backend implementation will convert the key to a string using its toString() method.

      Returns:
      if the backend loads all keys as strings, and writes them as strings likewise