fi.helsinki.dacopan.scenario
Class ScenarioFile

java.lang.Object
  fi.helsinki.dacopan.scenario.ScenarioFile

public class ScenarioFile
extends java.lang.Object

Implements loading and saving of scenario data, including animation sequence, settings and protocol events data. Each of the objects that wishes to save its state to the file should implement Saveable to provide this class with the data to be saved.

The scenario file is backed by a standard Jar archive.

Usage

To create a new scenario file, you must provide the default constructor with the target file where the information should be saved along with the protocol events data that is to be saved in the file. For example:

 Reader protocolData = ...; // protocol data from some source
 ScenarioFile file = new ScenarioFile(new File("myscenario.jar"), protocolData);
 

Note: creating a new scenario file always overwrites any existing one with the same name.

The previous step created a scenario file with nothing but the protocol events data. To save other data (e.g. settings), you must provide the ScenarioFile instance with a collection of saveables. For example:

 // two example classes that implement Saveable
 class MyClass implements Saveable {
   private String data; // the data that will be saved
   public Object getData() { return data }
   public void setData(Object o) { this.data = (String)data; }
 }
 class MyOtherClass implements Saveable {
   private Integer data;
   public Object getData() { return data }
   public void setData(Object o) { this.data = (String)data; }
 }
 
 // instances of these classes
 MyClass myObject = new MyClass("abc");
 MyOtherClass myOtherObject = new MyOtherClass(new Integer(123));
 
 // save them to the scenario file
 Collection toBeSaved = new LinkedList();
 toBeSaved.add(myObject);
 toBeSaved.add(myOtherObject);
 file.save(toBeSaved);
 

Note: the save(Collection) -method doesn't save the Saveable objects themselves, but the values returned from their Saveable.getData() -methods.

To load a scenario file, use the single-parameter constructor that accepts a file. The constructor will throw an exception if the given file is not a valid scenario file.

 // fails with InvalidScenarioFileException if existing is not a valid scenario file
 ScenarioFile file = new ScenarioFile(existing); 
 

To load the values saved before, you have to provide the ScenarioFile with a collection of Saveables whose values are to be loaded back along with a DataView that is to be populated with the saved protocol data. For example:

 DataView emptyDataView = ...;
 Collection toBePopulated = new LinkedList();
 toBePopulated.add(myObject);
 toBePopulated.add(myOtherObject);
 
 file.load(toBePopulated, emptyDataView);
 

The load(Collection) -method calls the Saveable.setData(Object) -method of each Saveable passed to it with the saved value as a parameter.

Version:

$Id: ScenarioFile.java,v 1.10 2005/05/05 20:32:34 tituomin Exp $

Constructor Summary

ScenarioFile(java.io.File file)
Loads an existing scenario file.

ScenarioFile(java.io.File file, java.util.Collection saveables)
Saves a global settings file

ScenarioFile(java.io.File file, java.io.Reader protocolDataReader)
Creates (or overwrites existing) an empty scenario file with given protocol data.

Method Summary

java.io.File	getArchiveFile() Returns the actual file that contains the scenario data.
void	load(java.util.Collection saveables) Populates the given collection of Saveable objects from this scenario file.
void	load(java.util.Collection saveables, DataView view, ProgressIndicator indicator) Populates the given collection of Saveables and the DataView from
void	populateView(DataView view) Populates the given DataView with the protocol data using XMLProtocolEventsReader.
void	populateView(DataView view, ProgressIndicator indicator)
void	save(java.util.Collection saveables) Retrieves data from the given collection of Saveable objects and saves them to this scenario file.
protected void	saveFile(java.io.Reader protocolDataReader, java.util.Collection saveables) Saves the scenario file with the protocol events data and a collection of saveables.
void	setObjectSerializer(ObjectSerializer serializer) Sets the object serializer to be used when saving objects.

Methods inherited from class java.lang.Object

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

Constructor Detail

ScenarioFile

public ScenarioFile(java.io.File file,
                    java.io.Reader protocolDataReader)
             throws java.io.IOException

Creates (or overwrites existing) an empty scenario file with given protocol data.

Parameters:

file - in which to store the scenario data

protocolDataReader - reader that provides the protocol data of the scenario

Throws:

java.io.IOException - if creating the file fails

ScenarioFile

public ScenarioFile(java.io.File file)
             throws java.io.IOException,
                    java.io.FileNotFoundException,
                    InvalidScenarioFileException

Loads an existing scenario file.

Parameters:

file - the archive file, must exist

Throws:

java.io.IOException - if loading the file fails

java.io.FileNotFoundException - if the scenario file doesn't exist

InvalidScenarioFileException - if the file is not a valid scenario file

ScenarioFile

public ScenarioFile(java.io.File file,
                    java.util.Collection saveables)
             throws java.io.IOException,
                    InvalidScenarioFileException

Saves a global settings file

Parameters:

file - The settings file

saveables - Collection of settings objects

Throws:

java.io.IOException - if saving fails due to I/O problems

InvalidScenarioFileException - if the file is not a valid scenariofile

Method Detail

save

public void save(java.util.Collection saveables)
          throws java.io.IOException

Retrieves data from the given collection of Saveable objects and saves them to this scenario file. Any existing data is overridden.

Parameters:

saveables - collection of Saveable objects

Throws:

java.io.IOException - if saving fails due to I/O problems

load

public void load(java.util.Collection saveables)
          throws java.io.IOException

Populates the given collection of Saveable objects from this scenario file.

Throws:

java.io.IOException - if loading fails

load

public void load(java.util.Collection saveables,
                 DataView view,
                 ProgressIndicator indicator)
          throws java.io.IOException

Populates the given collection of Saveables and the DataView from

Throws:

java.io.IOException - if loading fails

populateView

public void populateView(DataView view)
                  throws java.io.IOException

Populates the given DataView with the protocol data using XMLProtocolEventsReader.

Parameters:

view - to be populated

Throws:

java.io.IOException - if reading fails

populateView

public void populateView(DataView view,
                         ProgressIndicator indicator)
                  throws java.io.IOException

Throws:

java.io.IOException

See Also:

populateView(DataView)

getArchiveFile

public java.io.File getArchiveFile()

Returns the actual file that contains the scenario data.

setObjectSerializer

public void setObjectSerializer(ObjectSerializer serializer)

Sets the object serializer to be used when saving objects. The default is XStreamObjectSerializer.

saveFile

protected void saveFile(java.io.Reader protocolDataReader,
                        java.util.Collection saveables)
                 throws java.io.IOException

Saves the scenario file with the protocol events data and a collection of saveables.

Throws:

java.io.IOException