jawiro
Class PersistenceManager

java.lang.Object
  jawiro.PersistenceManager

public class PersistenceManager
extends java.lang.Object

Persistence capability is added to JAWIRO by using the Java Serialization API, so that users are able to save entire role hierarchies to secondary storage devices for later use. The PersistenceManager class is responsible from secure storage and retrieval of role hierarchies. 64-bit DES algorithm is chosen for encryption as it is commonly available in many operating systems. Users can create subclasses of the PersistenceManager class for better encryption.

Persistence mechanism is enhanced, so that all participants of the same role hierarchy is serialized to disk within the same file. Otherwise, a problem which is to be named as "the broken reference problem" would arise: Consider the situation where a participant of a role hierarchy has one or more references to other participants of the same role hierarchy. For example, a particular participant of the hierarchy may have a collection data structure where other Role or Actor instances are stored. After serialization, the former object no longer has references to the latter objects; it only has copies of the latter objects. In that case, the programmer would have to explicitly check the copies and merge those two copies into one object.

Although the broken reference problem is eliminated for the participants of the same role hierarchy, references between participants of different role hierarchies will still be "broken" after deserialization. In order to prevent the broken reference problem, the programmer needs to use the public boolean upload( String[] keys, Actor... actorList ) method for serializing the related hierarchies together into the same file and the download(String[],Actor...) method for deserializing the hierarchies together.

Constructor Summary

PersistenceManager(java.lang.String path, java.lang.String name)

Method Summary

boolean	checkAvailability(java.lang.Object anActor, java.lang.String key) Checks whether an Actor instance, e.g. a given role hierarchy, is associated with a given key or not.
boolean	checkAvailability(java.lang.String key) Checks whether a role hierarchy associated with a given key exists or not.
java.lang.Object	download(java.lang.String key) The method for loading a role hierarchy from the secondary storage, e.g. downloading a role hierarchy from the persistency manager.
boolean	download(java.lang.String[] keys, jawiro.Actor... actorList) The method for loading multiple hierarchies from disk.
java.lang.String	register(java.lang.Object anActor) If a role hierarchy needs to be persistent, its root must be registered with a persistence manager by using this method.
boolean	register(java.lang.Object anActor, java.lang.String key) If a role hierarchy needs to be persistent, its root must be registered with a persistence manager by using this method.
boolean	saveTable() Saves the persistency table to disk in encrypted form.
boolean	unregister(java.lang.String key) If a role hierarchy is no longer needed to be persistent, its root is unregistered.
boolean	upload(java.lang.Object anActor, java.lang.String key) A role hierarchy registered previously with a persistence manager can be saved to secondary storage, e.g. uploaded to the persistence manager with this method.
boolean	upload(java.lang.String[] keys, jawiro.Actor... actorList) The method for saving multiple hierarchies to disk.

Methods inherited from class java.lang.Object

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

Constructor Detail

PersistenceManager

public PersistenceManager(java.lang.String path,
                          java.lang.String name)

Parameters:

path - The path where the persistency table and the serialized objects are stored.

name - The name of the file where the entries of the persistency table are kept in encrypted form.

Method Detail

register

public java.lang.String register(java.lang.Object anActor)

If a role hierarchy needs to be persistent, its root must be registered with a persistence manager by using this method. This version of registration automatically generates a key for this Actor instance by using the Object.hashCode method. If the generated key is already associated with another hierarchy, the operation fails.

Parameters:

anActor - The root of a role hierarchy which is needed to be persistent.

Returns:

The key for this role hierarchy or null if the operation is unsuccessful.

See Also:

register(Object, String)

register

public boolean register(java.lang.Object anActor,
                        java.lang.String key)

If a role hierarchy needs to be persistent, its root must be registered with a persistence manager by using this method. If the generated key is already associated with another hierarchy, the operation fails.

Parameters:

anActor - The root of a role hierarchy which is needed to be persistent.

key - The key for this role hierarchy.

Returns:

true if the operation is successful, false otherwise.

unregister

public boolean unregister(java.lang.String key)

If a role hierarchy is no longer needed to be persistent, its root is unregistered. This method removes the Actor object with the given key from the persistence table and deletes all associated files from the disk.

Parameters:

key - The key for this role hierarchy.

Returns:

true if the operation is successful, false if there is no hierarchy associated with the given key.

checkAvailability

public boolean checkAvailability(java.lang.String key)

Checks whether a role hierarchy associated with a given key exists or not.

Parameters:

key - A key to be checked

Returns:

true if there is a role hierarchy associated with this key.

checkAvailability

public boolean checkAvailability(java.lang.Object anActor,
                                 java.lang.String key)

Checks whether an Actor instance, e.g. a given role hierarchy, is associated with a given key or not.

Parameters:

anActor - The Actor instance which will be compared with the key.

key - The key which will be compared with the Actor instance

Returns:

true if the given key belongs to the given role hierarchy, false if otherwise.

upload

public boolean upload(java.lang.Object anActor,
                      java.lang.String key)

A role hierarchy registered previously with a persistence manager can be saved to secondary storage, e.g. uploaded to the persistence manager with this method. The key must be correct in order to proceed with uploading. JAWIRO handles the rest of the procedure as follows:

• The persistence manager serializes the Actor instance to disk and encrypts the file.
• The Actor.hierarchy member serializes the rest of the hierarchy.
• The Actor.hierarchy member creates a file which contains role binding information for this hierarchy
• The persistence manager encrypts all files created during this process.

In order to prevent the broken reference problem between multiple hierarchies, use the PersistenceManager.upload(String[], Actor[]) method. This problem is eliminated within the same hierarchy.

Parameters:

anActor - The root of a role hierarchy which will be saved to secondary storage.

key - The key for this role hierarchy.

Returns:

true if the role hierarchy has been saved to secondary storage sucessfully, false if otherwise.

See Also:

upload(String[], Actor[])

upload

public boolean upload(java.lang.String[] keys,
                      jawiro.Actor... actorList)

The method for saving multiple hierarchies to disk. In order to solve the broken reference problem between multiple hierarchies, this version of the upload method should be used.

Parameters:

keys - The array containing the keys of the role hierarchies which are to be saved to disk. The order of the keys and the related Actor objects must be the same.

actorList - The roots of the hierarchies which are to be saved to disk. The order of the keys and the related Actor objects must be the same.

Returns:

true if the operation is successful.

See Also:

upload(Object, String)

download

public java.lang.Object download(java.lang.String key)

The method for loading a role hierarchy from the secondary storage, e.g. downloading a role hierarchy from the persistency manager. User must supply a key which is already associated with a role hierarchy. JAWIRO handles the rest of the procedure as follows:

The root instance is deserialized from the secondary storage.

The persistency manager checks whether the given key is registered with the same type name as the type of the jawiro.Actor instance. If types are matched, the procedure continues.

The PM instantiates and deserializes the role objects belonging to the rest of the hierarchy.

The PM instance adds the role objects to the role hierarchy in correct order.

In order to prevent the broken reference problem between multiple hierarchies, use the PersistenceManager.download(String[], Actor[]) method. This problem is eliminated within the same hierarchy.

Parameters:

key - The key for the role hierarchy to be loaded from secondary storage.

Returns:

The root of the loaded role hierarchy in case of a successful operation, null otherwise.

See Also:

download(String[], Actor[])

download

public boolean download(java.lang.String[] keys,
                        jawiro.Actor... actorList)

The method for loading multiple hierarchies from disk. In order to solve the broken reference problem between multiple hierarchies, this version of the download method should be used.

Parameters:

keys - The array containing the keys of the role hierarchies which are to be loaded from disk. The order of the keys and the related Actor objects must be the same.

actorList - The roots of the hierarchies which are to be loaded from disk. The actor instances should be initialized with any available constructor before this command. The order of the keys and the related Actor objects must be the same.

Returns:

true if the operation is successful.

See Also:

download(String)

saveTable

public boolean saveTable()

Saves the persistency table to disk in encrypted form. This method is automatically run after each registeration and unregistration operation.

Returns:

true if the operation is sucessful, false otherwise.

See Also:

register(Object), register(Object,String), unregister(String)