Convenience Classes For Auto-persisting Containers

[CrazyKidJack]

Overview

This would add 6 convenience classes to the library which would allow users to easily create auto-persisting objects / containers.

• PersistedContainer
  • PersistedCollection
  • PersistedList
  • PersistedSet
  • PersistedMap
  • PersistedObject

Note that modifications made to the contents of the containers via direct references to those contents (for example a reference to an element of a PersistedList) cannot be automatically persisted because the container has no way to know what you are doing with that reference. Therefore, modifications made in this manner require either explicit calls to the PersistedContainer::save() method or custom implementations of the element types that either do the saving or notify the PersistedContainer of the changes.

Related PR: I believe this PR would no longer be necessary if THIS PR gets approved.

PersistedContainer

This is the abstract parent of all auto-persisting things. It encapsulates the creation of the Preferences as well as provides a public save() function to persist the current state of the container.

Persisted Collections and PersistedMap

These classes are designed to have an api that is as compliant with the Java Collections Framework as possible. These classes allow users to create collections that work like any other collection, but that automatically persist themselves using the Preferences class.

These classes allow user's to have auto-persisting things, without have to do any custom implementation of any kind (though of course they could if they wanted to). These classes implement standard Java Collections Framework interfaces but are really only proxies for pre-existing implementations. This means that these classes must be given an instance of some other implementation as the proxy target and any methods provided only by that particular implementation will not be available for auto-persistence without creating custom extensions of these classes (which should not actually be too difficult if one wanted).

Some notable departures from the Java Collections Framework API is that these classes:

• Do not have no-arg constructors
• Are merely proxies for existing Java Collections Framework interface implementations that detect modifications and use Preferences to persist those modifications.

PersistedObject

Abstract base class that allows users to easily create custom objects that are auto-persisted. Extending this class is the preferred method to auto-persist data. But it also requires the most effort (which is why the other classes exist).

As the purpose of this class is to allow easy auto-persistence of CUSTOM classes, some (a very small part) of the implementation is left to the user. For example:

• child classes must have a reflection-accessible (usually could be private) no-arg constructor that creates a "default" instance for use by the Preferences:register() method.
  • This is a design choice and could be handled in several different ways instead. Including but not limited to:
  • having an instance method (not a constructor) return the default instance
  • having the PersistedObjects hold an _internalObject more similar to the PersistedCollection and PersistedMap classes.
  • forcing users to implement a clone() instance method that creates a copy of the initial (default) state of the object (conceptually I think I actually like this best... but if your auto-persisted custom object contains other objects, then the user would have to handle the cloning all the way down the tree and that clone method would have to change any time any part of the tree changed unless reflection is used. This could be partially mitigated by constituents implementing their own clone() method... but it will never be perfect)
• child classes should handle loading the values of their data members from _prefs
  • Relatedly, if desired, child classes would have to provide their own reset() methods. PersistedObject provides a reset() proxy method that resets the Preferences instance... but PersistedObject cannot (without reflection) know what fields then need to be retrieved from the reset _prefs.
• child classes need to call register(). This allows them to set custom default values by passing them in as arguments... However, that was actually an artifact of an earlier version in which I was trying to use the object's default state itself as the default value (which doesn't work because Preferences stores a reference to the default object, not a copy) and now I'm not sure it is actually useful any more (because I'm requiring the no-arg constructor to be defined and using it to get the default value). Therefore, it may be better to actually remove this requirement with a slight modification of the PersistedObject class.

Example Usage

A sample Burp Extension that uses these features can be found here.

Please note that it also uses some other features for which I have submitted PRs / issues but that may not yet have been pulled into this repo. A working version of a fork of this repo with all of features used by the sample extension can be found here (tag 1.1.0-beta.0.1.0).

If you trust them, I have created releases with jars that you can load and run to save you the trouble of building:

• BurpMontoyaUtilities
• Sample Extension

[CrazyKidJack]

Note, this PR now contains a small change to the Preferences class. Namely,

• it adds the reregister() function
• it makes unregister() only delete the data from persistence... not from memory

[CoreyD97]

Thanks for the PR, great suggestion and implementation. Mind if I use your description from this for the readme?

[CrazyKidJack]

Thanks for the PR, great suggestion and implementation. Mind if I use your description from this for the readme?

Yes feel free!