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