Package hudson.plugins.project_inheritance.util

Class VersionedObjectStore

java.lang.Object

hudson.plugins.project_inheritance.util.VersionedObjectStore

All Implemented Interfaces:

Serializable

public class VersionedObjectStore
extends Object
implements Serializable

This class allows you to version-control almost arbitrary objects. TODO: This class is in heavy need of a read/write lock TODO: Improve the JavaDoc of this class.

Author:

mhschroe

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	VersionedObjectStore.Version

Constructor Summary

Constructors

Constructor	Description
VersionedObjectStore()

Method Summary

Modifier and Type	Method	Description
boolean	areIdentical(VersionedObjectStore.Version v1, VersionedObjectStore.Version v2)
VersionedObjectStore.Version	createNextVersion()	This method creates the next version and copies all key/value object entries from the previous one.
VersionedObjectStore.Version	createNextVersionAsEmpty()	Creates the next version with an empty key/value object mapping.
VersionedObjectStore.Version	createNextVersionWithMapping(Map<String,Object> map)
Collection<HashMap<String,Object>>	getAllValueMaps()
SortedSet<VersionedObjectStore.Version>	getAllVersions()	Returns a new set of all versions, sorted by their ID in ascending order.
LinkedList<VersionedObjectStore.Version>	getAllVersionsSince(Long sinceVersionId)	gets all the more recent version ids since the sinceVersionId
VersionedObjectStore.Version	getLatestStable()
VersionedObjectStore.Version	getLatestVersion()	This retrieves the actual last versioned object.
VersionedObjectStore.Version	getNearestTo(Long timestamp)
Object	getObject(VersionedObjectStore.Version version, String key)
Object	getObject(Long id, String key)
VersionsNotification	getUserNotificationFor(Long version)	This method generates a notification to the user, depending on what type of version currently being edited: user is editing an unstable version (Warning) user is editing the last stable version which is not the last version (Warning) user is editing the last stable version which is the last version (Info) user is editing some stable version which is not the latest stable version (Warning)
Map<String,Object>	getValueMapFor(Long id)	This returns an immutable map that wraps around the key/value object map associated with the given version.
VersionedObjectStore.Version	getVersion(Long id)
static VersionedObjectStore	load(File file)	Loads a VersionedObjectStore from the given file.
void	save(File file)	Calling this function causes the store to be saved to disk.
boolean	setObjectFor(VersionedObjectStore.Version v, String key, Object value)
int	size()
String	toString()
String	toXML()
void	undoVersion(VersionedObjectStore.Version v)	This function removes the given version from the internal storage, if it is the last version that is present.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

VersionedObjectStore

public VersionedObjectStore()

Method Detail

toString

public String toString()

Overrides:

toString in class Object

toXML

public String toXML()

size

public int size()

save

public void save(File file)
          throws IOException

Calling this function causes the store to be saved to disk. Not making the save automatic allows you to make bulk-changes and only dump them to disk once finished. Do note that while the function itself is synchronized, at the moment nothing prevents others to change the underlying data fields during save. TODO: Fix this, so that saves are truly atomic. Do note that this function fails silently in case the output file is not writable. It will log an error, but do nothing beyond that

Parameters:

file - the file to save the data to. The data is dumped as GZIP-compressed XML.

Throws:

IOException - in case the save file can't be read.

load

public static VersionedObjectStore load(File file)
                                 throws IllegalArgumentException,
                                        IOException,
                                        com.thoughtworks.xstream.XStreamException

Loads a VersionedObjectStore from the given file.

Parameters:

file - the file to load data from. Must be XML -- either raw or GZIP compressed.

Returns:

a newly created VersionedObjectStore.

Throws:

IOException - in case the file can't be read.

IllegalArgumentException - in case the file contains invalid data.

com.thoughtworks.xstream.XStreamException - in case of XML serialisation error

areIdentical

public boolean areIdentical(VersionedObjectStore.Version v1,
                            VersionedObjectStore.Version v2)

getLatestVersion

public VersionedObjectStore.Version getLatestVersion()

This retrieves the actual last versioned object.

Returns:

the latest version, or null if no version exists

getVersion

public VersionedObjectStore.Version getVersion(Long id)

getLatestStable

public VersionedObjectStore.Version getLatestStable()

getAllVersionsSince

public LinkedList<VersionedObjectStore.Version> getAllVersionsSince(Long sinceVersionId)

gets all the more recent version ids since the sinceVersionId

Parameters:

sinceVersionId - timestamp in milliseconds since the epoch

Returns:

all versions since the given timestamp

getNearestTo

public VersionedObjectStore.Version getNearestTo(Long timestamp)

getAllVersions

public SortedSet<VersionedObjectStore.Version> getAllVersions()

Returns a new set of all versions, sorted by their ID in ascending order.

Returns:

a sorted set of versions in ascending order.

getAllValueMaps

public Collection<HashMap<String,Object>> getAllValueMaps()

createNextVersion

public VersionedObjectStore.Version createNextVersion()

This method creates the next version and copies all key/value object entries from the previous one.

Returns:

a blank next version.

undoVersion

public void undoVersion(VersionedObjectStore.Version v)

This function removes the given version from the internal storage, if it is the last version that is present.

You should not expose this function to the outside. Ever!

Parameters:

v - the version to commit

createNextVersionAsEmpty

public VersionedObjectStore.Version createNextVersionAsEmpty()

Creates the next version with an empty key/value object mapping.

Returns:

a blank, next version

createNextVersionWithMapping

public VersionedObjectStore.Version createNextVersionWithMapping(Map<String,Object> map)

getObject

public Object getObject(Long id,
                        String key)

getObject

public Object getObject(VersionedObjectStore.Version version,
                        String key)

getValueMapFor

public Map<String,Object> getValueMapFor(Long id)

This returns an immutable map that wraps around the key/value object map associated with the given version.

Use this method in favour of getObject(Long, String) to avoid the O(log(n)) cost of retrieving the given version if you access more than one stored object.

Parameters:

id - the numerical ID of the version to retrieve

Returns:

an immutable map of key/value object pairs

setObjectFor

public boolean setObjectFor(VersionedObjectStore.Version v,
                            String key,
                            Object value)

getUserNotificationFor

public VersionsNotification getUserNotificationFor(Long version)

This method generates a notification to the user, depending on what type of version currently being edited:

1. user is editing an unstable version (Warning)
2. user is editing the last stable version which is not the last version (Warning)
3. user is editing the last stable version which is the last version (Info)
4. user is editing some stable version which is not the latest stable version (Warning)

Parameters:

version - the specific version for which to get the notification

Returns:

a notification about the suitability of the given version