uk.ac.vamsas.client.simpleclient
Class VamsasArchive

java.lang.Object
  extended byuk.ac.vamsas.client.simpleclient.VamsasArchive

public class VamsasArchive
extends java.lang.Object

Class for high-level io and Jar manipulation involved in creating or updating a vamsas archive (with backups). Writes to a temporary file and then swaps new file for backup. uses the sessionFile locking mechanism for safe I/O

Author:
jimp

Field Summary
protected  SimpleDocument vorba
           
 
Constructor Summary
VamsasArchive(java.io.File archive, boolean vamsasdocument)
          Create a new vamsas archive File locks are made immediately to avoid contention
VamsasArchive(java.io.File archive, boolean vamsasdocument, boolean overwrite)
           
VamsasArchive(java.io.File archive, boolean overwrite, boolean vamsasdocument, SessionFile extantLock)
           
VamsasArchive(VamsasFile archive)
          read and write to archive - will not overwrite original contents, and will always write an up to date vamsas document structure.
VamsasArchive(VamsasFile archive, boolean vamsasdocument, boolean overwrite)
          Constructor for accessing Files under file-lock management (ie a session file)
 
Method Summary
protected  boolean _validNewAppDataReference(java.lang.String newAppDataReference)
          Validates the AppDataReference: not null and not already written to archive.
 java.io.File backupFile()
          called by app to get name of backup if it was made.
 boolean cancelArchive()
          Stops any current write to archive, and reverts to the backup if it exists.
 void closeArchive()
          Tidies up and closes archive, removing any backups that were created.
 AppDataOutputStream getAppDataStream(java.lang.String appdataReference)
          Opens and returns the applicationData output stream for the appdataReference string.
protected  java.lang.String getDocumentJarEntry()
           
 java.io.PrintWriter getDocumentOutputStream()
          Safely initializes the VAMSAS XML document Jar Entry.
 VamsasArchiveReader getOriginalArchiveReader()
          Access original archive if it exists, pass the reader to the client Note: this is NOT thread safe and a call to closeArchive() will by necessity close and invalidate the VamsasArchiveReader object.
 Vobject[] getOriginalRoots()
          returns original document's root vamsas elements.
static Vobject[] getOriginalRoots(VamsasArchive ths)
          Access original document if it exists, and get VAMSAS root objects.
static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths)
          Access the original vamsas document for a VamsasArchive class, and return it.
static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths, VorbaIdFactory vorba)
          Uses VorbaXmlBinder to retrieve the VamsasDocument from the original archive referred to by ths
 VamsasDocument getVamsasDocument()
           
 VamsasDocument getVamsasDocument(java.lang.String provenance_user, java.lang.String provenance_action, java.lang.String version)
          Return the original document or a new empty document with initial provenance entry.
 VorbaIdFactory getVorba()
           
protected  boolean isDocumentWritten()
           
 void putVamsasDocument(VamsasDocument doc)
           
 void putVamsasDocument(VamsasDocument doc, VorbaIdFactory vorba)
           
 void setVorba(VorbaIdFactory Vorba)
           
 boolean transferAppDataEntry(java.lang.String AppDataReference)
          Convenience method to copy over the referred entry from the backup to the new version.
 boolean transferAppDataEntry(java.lang.String AppDataReference, java.lang.String NewAppDataReference)
          Transfers an AppDataReference from old to new vamsas archive, with a name change.
 boolean transferRemainingAppDatas()
          transfers any AppDataReferences existing in the old document that haven't already been transferred to the new one LATER: do the same for transfers requiring a namechange - more document dependent.
 boolean writeAppdataFromStream(java.lang.String AppDataReference, java.io.InputStream adstream)
          write data from a stream into an appData reference.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

vorba

protected SimpleDocument vorba
Constructor Detail

VamsasArchive

public VamsasArchive(java.io.File archive,
                     boolean vamsasdocument)
              throws java.io.IOException
Create a new vamsas archive File locks are made immediately to avoid contention

Parameters:
archive - - file spec for new vamsas archive
vamsasdocument - true if archive is to be a fully fledged vamsas document archive
Throws:
java.io.IOException - if call to accessOriginal failed for updates, or openArchive failed.

VamsasArchive

public VamsasArchive(java.io.File archive,
                     boolean vamsasdocument,
                     boolean overwrite)
              throws java.io.IOException

VamsasArchive

public VamsasArchive(VamsasFile archive,
                     boolean vamsasdocument,
                     boolean overwrite)
              throws java.io.IOException
Constructor for accessing Files under file-lock management (ie a session file)

Parameters:
archive -
vamsasdocument -
overwrite -
Throws:
java.io.IOException

VamsasArchive

public VamsasArchive(VamsasFile archive)
              throws java.io.IOException
read and write to archive - will not overwrite original contents, and will always write an up to date vamsas document structure.

Parameters:
archive -
Throws:
java.io.IOException

VamsasArchive

public VamsasArchive(java.io.File archive,
                     boolean overwrite,
                     boolean vamsasdocument,
                     SessionFile extantLock)
              throws java.io.IOException
Parameters:
archive - file to write
overwrite - true if original contents should be deleted
vamsasdocument - true if a proper VamsasDocument archive is to be written.
extantLock - SessionFile object holding a lock for the archive
Throws:
java.io.IOException
Method Detail

getOriginalRoots

public static Vobject[] getOriginalRoots(VamsasArchive ths)
                                  throws java.io.IOException,
                                         org.exolab.castor.xml.MarshalException,
                                         org.exolab.castor.xml.ValidationException
Access original document if it exists, and get VAMSAS root objects.

Returns:
vector of vamsas roots from original document
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

getOriginalVamsasDocument

public static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths)
                                                throws java.io.IOException,
                                                       org.exolab.castor.xml.MarshalException,
                                                       org.exolab.castor.xml.ValidationException
Access the original vamsas document for a VamsasArchive class, and return it. Users of the VamsasArchive class should use the getVamsasDocument method to retrieve the current document - only use this one if you want the 'backup' version. TODO: catch OutOfMemoryError - they are likely to occur here. NOTE: vamsas.xml datastreams are constructed as 'ALPHA_VERSION' vamsas documents.

Parameters:
ths -
Returns:
null if no document exists.
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

getOriginalVamsasDocument

public static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths,
                                                       VorbaIdFactory vorba)
                                                throws java.io.IOException,
                                                       org.exolab.castor.xml.MarshalException,
                                                       org.exolab.castor.xml.ValidationException
Uses VorbaXmlBinder to retrieve the VamsasDocument from the original archive referred to by ths

Parameters:
ths -
vorba -
Returns:
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

backupFile

public java.io.File backupFile()
called by app to get name of backup if it was made. If this is called, the caller app *must* delete the backup themselves.

Returns:
null or a valid file object

cancelArchive

public boolean cancelArchive()
Stops any current write to archive, and reverts to the backup if it exists. All existing locks on the original will be released. All backup files are removed.


closeArchive

public void closeArchive()
                  throws java.io.IOException
Tidies up and closes archive, removing any backups that were created. NOTE: It is up to the caller to delete the original archive backup obtained from backupFile() TODO: ensure all extant AppDataReference jar entries are transferred to new Jar TODO: provide convenient mechanism for generating new unique AppDataReferences and adding them to the document

Throws:
java.io.IOException

getAppDataStream

public AppDataOutputStream getAppDataStream(java.lang.String appdataReference)
                                     throws java.io.IOException
Opens and returns the applicationData output stream for the appdataReference string.

Parameters:
appdataReference -
Returns:
Output stream to write to
Throws:
java.io.IOException

getDocumentJarEntry

protected java.lang.String getDocumentJarEntry()
Returns:
JarEntry name for the vamsas XML stream in this archive

getDocumentOutputStream

public java.io.PrintWriter getDocumentOutputStream()
                                            throws java.io.IOException
Safely initializes the VAMSAS XML document Jar Entry.

Returns:
Writer to pass to the marshalling function.
Throws:
java.io.IOException - if a document entry has already been written.

getOriginalArchiveReader

public VamsasArchiveReader getOriginalArchiveReader()
                                             throws java.io.IOException
Access original archive if it exists, pass the reader to the client Note: this is NOT thread safe and a call to closeArchive() will by necessity close and invalidate the VamsasArchiveReader object.

Returns:
null if no original archive exists.
Throws:
java.io.IOException

getOriginalRoots

public Vobject[] getOriginalRoots()
                           throws java.io.IOException,
                                  org.exolab.castor.xml.MarshalException,
                                  org.exolab.castor.xml.ValidationException
returns original document's root vamsas elements.

Returns:
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

getVamsasDocument

public VamsasDocument getVamsasDocument()
                                 throws java.io.IOException,
                                        org.exolab.castor.xml.MarshalException,
                                        org.exolab.castor.xml.ValidationException
Returns:
original document or a new empty document (with default provenance)
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

getVamsasDocument

public VamsasDocument getVamsasDocument(java.lang.String provenance_user,
                                        java.lang.String provenance_action,
                                        java.lang.String version)
                                 throws java.io.IOException,
                                        org.exolab.castor.xml.MarshalException,
                                        org.exolab.castor.xml.ValidationException
Return the original document or a new empty document with initial provenance entry.

Parameters:
provenance_user - (null sets user to be the class name)
provenance_action - (null sets action to be 'created new document')
version - (null means use latest version)
Returns:
(original document or a new vamsas document with supplied provenance and version info)
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

getVorba

public VorbaIdFactory getVorba()
Returns:
Returns the current VorbaIdFactory for the archive.

isDocumentWritten

protected boolean isDocumentWritten()
Returns:
true if Vamsas Document has been written to archive

putVamsasDocument

public void putVamsasDocument(VamsasDocument doc)
                       throws java.io.IOException,
                              org.exolab.castor.xml.MarshalException,
                              org.exolab.castor.xml.ValidationException
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

putVamsasDocument

public void putVamsasDocument(VamsasDocument doc,
                              VorbaIdFactory vorba)
                       throws java.io.IOException,
                              org.exolab.castor.xml.MarshalException,
                              org.exolab.castor.xml.ValidationException
Parameters:
doc -
vorba -
Returns:
(vorbaId string, Vobjhash) pairs for last hash of each object in document
Throws:
java.io.IOException
org.exolab.castor.xml.MarshalException
org.exolab.castor.xml.ValidationException

setVorba

public void setVorba(VorbaIdFactory Vorba)

transferAppDataEntry

public boolean transferAppDataEntry(java.lang.String AppDataReference)
                             throws java.io.IOException
Convenience method to copy over the referred entry from the backup to the new version. Warning messages are raised if no backup exists or the entry doesn't exist in the backed-up original. Duplicate writes return true - but a warning message will also be raised.

Parameters:
AppDataReference -
Returns:
true if AppDataReference now exists in the new document
Throws:
java.io.IOException

_validNewAppDataReference

protected boolean _validNewAppDataReference(java.lang.String newAppDataReference)
                                     throws java.io.IOException
Validates the AppDataReference: not null and not already written to archive.

Returns:
true if valid. false if not
Throws:
java.io.IOException - for really broken references!

transferAppDataEntry

public boolean transferAppDataEntry(java.lang.String AppDataReference,
                                    java.lang.String NewAppDataReference)
                             throws java.io.IOException
Transfers an AppDataReference from old to new vamsas archive, with a name change.

Parameters:
AppDataReference -
NewAppDataReference - - AppDataReference in new Archive
Returns:
Throws:
java.io.IOException
See Also:
transferAppDataEntry(String AppDataReference)

writeAppdataFromStream

public boolean writeAppdataFromStream(java.lang.String AppDataReference,
                                      java.io.InputStream adstream)
                               throws java.io.IOException
write data from a stream into an appData reference.

Parameters:
AppDataReference - - New AppDataReference not already written to archive
adstream - Source of data for appData reference - read until .read(buffer) returns -1
Returns:
true on success.
Throws:
java.io.IOException - for file IO or invalid AppDataReference string

transferRemainingAppDatas

public boolean transferRemainingAppDatas()
                                  throws java.io.IOException
transfers any AppDataReferences existing in the old document that haven't already been transferred to the new one LATER: do the same for transfers requiring a namechange - more document dependent.

Returns:
true if data was transferred.
Throws:
java.io.IOException