Package ghidra.util.database

# Interface DBCachedObjectStoreFactory.DBFieldCodec<VT,OT extends DBAnnotatedObject,FT extends Field>

Type Parameters:
  `VT` - the type of the value encoded, i.e., the object field's Java type
  `OT` - the upper bound on objects containing the field
  `FT` - the type of the database field into which the value is encoded

All Known Implementing Classes:
  `AbstractDBTracePropertyMap.SaveableDBFieldCodec`, `DBAnnotatedField.DefaultCodec`, `DBCachedObjectStoreFactory.AbstractDBFieldCodec`, `DBCachedObjectStoreFactory.BooleanDBFieldCodec`, `DBCachedObjectStoreFactory.ByteArrayDBFieldCodec`, `DBCachedObjectStoreFactory.ByteDBFieldCodec`, `DBCachedObjectStoreFactory.EnumDBByteFieldCodec`, `DBCachedObjectStoreFactory.IntDBFieldCodec`, `DBCachedObjectStoreFactory.LongArrayDBFieldCodec`, `DBCachedObjectStoreFactory.LongDBFieldCodec`, `DBCachedObjectStoreFactory.ShortDBFieldCodec`, `DBCachedObjectStoreFactory.StringDBFieldCodec`, `DBCachedObjectStoreFactory.VariantDBFieldCodec`, `DBTraceObject.ObjectPathDBFieldCodec`, `DBTraceObjectDBFieldCodec`, `DBTraceObjectManager.DBTraceObjectSchemaDBFieldCodec`, `DBTraceOverlaySpaceAdapter.AddressDBFieldCodec`, `DBTraceSymbolManager.VariableStorageDBFieldCodec`, `DBTraceUtils.AbstractOffsetSnapDBFieldCodec`, `DBTraceUtils.CompilerSpecIDDBFieldCodec`, `DBTraceUtils.LanguageIDDBFieldCodec`, `DBTraceUtils.OffsetThenSnapDBFieldCodec`, `DBTraceUtils.RefTypeDBFieldCodec`, `DBTraceUtils.URLDBFieldCodec`

Enclosing class:
  `DBCachedObjectStoreFactory`

public static interface DBCachedObjectStoreFactory.DBFieldCodec<VT,OT extends DBAnnotatedObject,FT extends Field>
A codec for encoding alternative data types

The database framework supports limited types of fields, each capable for storing a specific Java data type. A simple codec is provided for "encoding" each of the supported types into its corresponding `Field` type. For other types, additional custom codecs must be implemented. Custom codecs must be explicitly selected using the `DBAnnotatedField.codec()` attribute.

NOTE: When changing the implementation of a codec, keep in mind whether or not it implies a change to the schema of tables that use the codec. If it does, their schema versions, i.e., `DBAnnotatedObjectInfo.version()` should be incremented and considerations made for supporting upgrades.

In some cases, the codec may require context information from the containing object. This is facilitated via the `DBCachedObjectStoreFactory.DBFieldCodec` type parameter. If no additional context is required, `DBAnnotatedObject` is sufficient. If context is required, then additional interfaces can be required via type intersection:

     public interface MyContext {
     	// ...
     }

     public interface ContextProvider {
     	MyContext getContext();
     }

     public static class MyDBFieldCodec<OT extends DBAnnotatedObject & ContextProvider> extends
     		AbstractDBFieldCodec<MyType, OT, BinaryField> {

     	public MyDBFieldCodec(Class<OT> objectType, Field field, int column) {
     		super(MyType.class, objectType, BinaryField.class, field, column);
     	}

     	@Override
     	protected void doStore(OT obj, DBRecord record) {
     		MyContext ctx = obj.getContext();
     		// ...
     	}
     	// ...
     }

Note that this implementation uses `DBCachedObjectStoreFactory.AbstractDBFieldCodec`, which is highly recommended. Whether or not the abstract codec is used, the constructor must have the signature `(Class<OT>, Field, int)`, which are the containing object's actual type, the field of the Java class whose values to encode, and the record column number into which to store those encoded values. The type variables `DBCachedObjectStoreFactory.DBFieldCodec` and `DBCachedObjectStoreFactory.DBFieldCodec` of the codec indicate it can encode values of type `MyType` into a byte array for storage into a `BinaryField`. See `DBCachedObjectStoreFactory.ByteDBFieldCodec` for the simplest example with actual encoding and decoding implementations. To use the example codec in an object:

     @DBAnnotatedObjectInfo(version = 1)
     public static class SomeObject extends DBAnnotatedObject implements ContextProvider {
     	static final String MY_COLUMN_NAME = "My";

     	@DBAnnotatedColumn(MY_COLUMN_NAME)
     	static DBObjectColumn MY_COLUMN;

     	@DBAnnotatedField(column = MY_COLUMN_NAME, codec = MyDBFieldCodec.class)
     	private MyType my;

     	// ...

     	@Override
     	public MyContext getContext() {
     		// ...
     	}
     }

Notice that `SomeObject` must implement `ContextProvider`. This restriction is checked at runtime when the object store is created, but a compile-time annotation processor can check this restriction sooner. This has been implemented, at least in part, in the `AnnotationProcessor` project. It is recommended that at most one additional interface is required in by `DBCachedObjectStoreFactory.DBFieldCodec`. If multiple contexts are required, consider declaring an interface that extends the multiple required interfaces. Alternatively, consider a new interface that provides one composite context.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default FT`
  `encodeField(VT value)`
  Encode the given value into a new field
  `Class<FT>`
  `getFieldType()`
  Get the type of field storing the values
  `Class<OT>`
  `getObjectType()`
  Get the upper bound on objects with fields using this codec
  `VT`
  `getValue(OT obj)`
  Get the value from the object
  `Class<VT>`
  `getValueType()`
  Get the type of values encoded and decoded
  `void`
  `load(OT obj, DBRecord record)`
  Decode the field from the given record into the given object
  `void`
  `store(OT obj, DBRecord record)`
  Encode the field from the given object into the given record
  `void`
  `store(VT value, FT f)`
  Encode the given field value into the given field

- ## Method Details

  - ### store

    void store(OT obj, DBRecord record)
    Encode the field from the given object into the given record
    Parameters:
      `obj` - the source object
      `record` - the destination record

  - ### store

    void store(VT value, FT f)
    Encode the given field value into the given field
    Parameters:
      `value` - the value
      `f` - the field

  - ### load

    void load(OT obj, DBRecord record)
    Decode the field from the given record into the given object
    Parameters:
      `obj` - the destination object
      `record` - the source record

  - ### getValueType

    Class<VT> getValueType()
    Get the type of values encoded and decoded
    Returns:
      the value type

  - ### getObjectType

    Class<OT> getObjectType()
    Get the upper bound on objects with fields using this codec
    Returns:
      the upper bound

  - ### getFieldType

    Class<FT> getFieldType()
    Get the type of field storing the values
    Returns:
      the field type

  - ### encodeField

    default FT encodeField(VT value)
    Encode the given value into a new field
    Parameters:
      `value` - the value
    Returns:
      the field with the encoded value

  - ### getValue

    VT getValue(OT obj)
    Get the value from the object
    Parameters:
      `obj` - the source object
    Returns:
      the value