Package ghidra.util

# Interface Saveable

All Known Implementing Classes:
  `GenericSaveable`, `IntArrayList`, `OldBookmark`, `PrivateSaveable`, `SaveableColor`, `SaveablePoint`

public interface Saveable
Save and restore elements that are compatible with ObjectStorage objects.

Important: Any class implementing this interface that may have its class path saved to the data base (i.e. user defined properties) should create a map in the `ClassTranslator` when it is moved or renamed between versions of Ghidra. It should also implement `ExtensionPoint`.

For example, any class that implements the `Saveable` interface can potentially be saved as a property in the program. If used as a program property the class name gets saved to a database field in the property manager. If the class gets moved or renamed, the property manager won't be able to instantiate it. The `ClassTranslator` allows the saveable class to indicate its old path name (that was stored in the database) and its current path name (the actual location of the class it needs to instantiate for the property).
The saveable class should call
`ClassTranslator.put(oldClassPath, newClassPath);`
in its static initializer.
The property manager would then call
`String newPathName = ClassTranslator.get(oldPathName);`
when it can't find the class for the old path name. If the new path name isn't null the property manager can use it to get the class.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Class<?>[]`
  `getObjectStorageFields()`
  Returns the field classes, in Java types, in the same order as used `save(ghidra.util.ObjectStorage)` and `restore(ghidra.util.ObjectStorage)`.
  `int`
  `getSchemaVersion()`
  Get the storage schema version.
  `boolean`
  `isPrivate()`
  Returns true if this saveable should not have it's changes broadcast.
  `boolean`
  `isUpgradeable(int oldSchemaVersion)`
  Determine if the implementation supports an storage upgrade of the specified oldSchemaVersion to the current schema version.
  `void`
  `restore(ObjectStorage objStorage)`
  Restore from the given ObjectStorage.
  `void`
  `save(ObjectStorage objStorage)`
  Save to the given ObjectStorage.
  `boolean`
  `upgrade(ObjectStorage oldObjStorage, int oldSchemaVersion, ObjectStorage currentObjStorage)`
  Upgrade an older stored object to the current storage schema.

- ## Method Details

  - ### getObjectStorageFields

    Class<?>[] getObjectStorageFields()
    Returns the field classes, in Java types, in the same order as used `save(ghidra.util.ObjectStorage)` and `restore(ghidra.util.ObjectStorage)`.

    For example, if the save method calls `objStorage.putInt()` and then `objStorage.putFloat()`, then this method must return `Class[]{ Integer.class, Float.class }`.

    Returns:

  - ### save

    void save(ObjectStorage objStorage)
    Save to the given ObjectStorage.
    Parameters:
      `objStorage` - Object that can handle Java primitives, Strings, and arrays of primitives and Strings

  - ### restore

    void restore(ObjectStorage objStorage)
    Restore from the given ObjectStorage.
    Parameters:
      `objStorage` - Object that can handle Java primitives, Strings, and arrays of primitives and Strings TODO: document how errors should be handled (i.e, exception, null return)

  - ### getSchemaVersion

    int getSchemaVersion()
    Get the storage schema version. Any time there is a software release in which the implementing class has changed the data structure used for the save and restore methods, the schema version must be incremented. NOTE: While this could be a static method, the Saveable interface is unable to define such methods.
    Returns:
      storage schema version.

  - ### isUpgradeable

    boolean isUpgradeable(int oldSchemaVersion)
    Determine if the implementation supports an storage upgrade of the specified oldSchemaVersion to the current schema version.
    Parameters:
      `oldSchemaVersion` -
    Returns:
      true if upgrading is supported for the older schema version.

  - ### upgrade

    boolean upgrade(ObjectStorage oldObjStorage, int oldSchemaVersion, ObjectStorage currentObjStorage)
    Upgrade an older stored object to the current storage schema.
    Parameters:
      `oldObjStorage` - the old stored object
      `oldSchemaVersion` - storage schema version number for the old object
      `currentObjStorage` - new object for storage in the current schema
    Returns:
      true if data was upgraded to the currentObjStorage successfully.

  - ### isPrivate

    boolean isPrivate()
    Returns true if this saveable should not have it's changes broadcast.
    Returns:
      true if this saveable should not have it's changes broadcast.