1 package uk.ac.vamsas.client.simpleclient;
3 import java.io.BufferedInputStream;
4 import java.io.BufferedOutputStream;
5 import java.io.DataOutputStream;
7 import java.io.IOException;
8 import java.io.InputStream;
9 import java.io.InputStreamReader;
10 import java.io.OutputStream;
11 import java.io.OutputStreamWriter;
12 import java.io.PrintWriter;
13 import java.util.Hashtable;
14 import java.util.Iterator;
15 import java.util.Vector;
16 import java.util.jar.JarEntry;
17 import java.util.jar.JarOutputStream;
18 import java.util.jar.Manifest;
20 import org.apache.commons.logging.Log;
21 import org.apache.commons.logging.LogFactory;
23 import uk.ac.vamsas.client.ClientHandle;
24 import uk.ac.vamsas.client.IVorbaIdFactory;
25 import uk.ac.vamsas.client.SessionHandle;
26 import uk.ac.vamsas.client.UserHandle;
27 import uk.ac.vamsas.client.Vobject;
28 import uk.ac.vamsas.client.VorbaIdFactory;
29 import uk.ac.vamsas.client.VorbaXmlBinder;
30 import uk.ac.vamsas.objects.core.ApplicationData;
31 import uk.ac.vamsas.objects.core.VAMSAS;
32 import uk.ac.vamsas.objects.core.VamsasDocument;
33 import uk.ac.vamsas.objects.utils.AppDataReference;
34 import uk.ac.vamsas.objects.utils.DocumentStuff;
35 import uk.ac.vamsas.objects.utils.ProvenanceStuff;
36 import uk.ac.vamsas.objects.utils.document.VersionEntries;
39 * Class for high-level io and Jar manipulation involved in creating
40 * or updating a vamsas archive (with backups).
41 * Writes to a temporary file and then swaps new file for backup.
42 * uses the sessionFile locking mechanism for safe I/O
46 public class VamsasArchive {
47 private static Log log = LogFactory.getLog(VamsasArchive.class);
49 * Access original document if it exists, and get VAMSAS root objects.
50 * @return vector of vamsas roots from original document
53 public static Vobject[] getOriginalRoots(VamsasArchive ths) throws IOException,
54 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
55 VamsasArchiveReader oReader = ths.getOriginalArchiveReader();
58 if (oReader.isValid()) {
59 InputStreamReader vdoc = new InputStreamReader(oReader.getVamsasDocumentStream());
60 VamsasDocument doc = VamsasDocument.unmarshal(vdoc);
62 return doc.getVAMSAS();
63 // TODO ensure embedded appDatas are garbage collected to save memory
65 InputStream vxmlis = oReader.getVamsasXmlStream();
66 if (vxmlis!=null) { // Might be an old vamsas file.
67 BufferedInputStream ixml = new BufferedInputStream(oReader.getVamsasXmlStream());
68 InputStreamReader vxml = new InputStreamReader(ixml);
69 VAMSAS root[] = new VAMSAS[1];
70 root[0] = VAMSAS.unmarshal(vxml);
79 * Access the original vamsas document for a VamsasArchive class, and return it.
80 * Users of the VamsasArchive class should use the getVamsasDocument method to retrieve
81 * the current document - only use this one if you want the 'backup' version.
82 * TODO: catch OutOfMemoryError - they are likely to occur here.
83 * NOTE: vamsas.xml datastreams are constructed as 'ALPHA_VERSION' vamsas documents.
85 * @return null if no document exists.
87 * @throws org.exolab.castor.xml.MarshalException
88 * @throws org.exolab.castor.xml.ValidationException
90 public static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths) throws IOException,
91 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
92 return VamsasArchive.getOriginalVamsasDocument(ths, null);
95 * Uses VorbaXmlBinder to retrieve the VamsasDocument from the original archive referred to by ths
100 * @throws org.exolab.castor.xml.MarshalException
101 * @throws org.exolab.castor.xml.ValidationException
103 public static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths, VorbaIdFactory vorba) throws IOException,
104 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
105 VamsasArchiveReader oReader = ths.getOriginalArchiveReader();
108 return ths.vorba.getVamsasDocument(oReader);
110 // otherwise - there was no valid original document to read.
114 * destination of new archive data (tempfile if virginarchive=true, original archive location otherwise)
116 java.io.File archive=null;
118 * locked IO handler for new archive file
120 SessionFile rchive=null;
122 * original archive file to be updated (or null if virgin) where new data will finally reside
124 java.io.File original=null;
126 * original archive IO handler
128 SessionFile odoclock = null;
129 Lock destinationLock = null;
131 * Original archive reader class
133 VamsasArchiveReader odoc = null;
135 * true if a real vamsas document is being written.
137 boolean vamsasdocument=true;
139 * Output stream for archived data
141 JarOutputStream newarchive=null;
143 * JarEntries written to archive
145 Hashtable entries = null;
148 * true if we aren't just updating an archive
150 private boolean virginArchive=false;
153 * name of backup of existing archive that has been updated/overwritten.
154 * only one backup will be made - and this is it.
156 File originalBackup = null;
158 boolean donotdeletebackup=false;
159 private final int _TRANSFER_BUFFER=4096*4;
160 protected SimpleDocument vorba = null;
162 * LATER: ? CUT'n'Paste error ?
163 * Access and return current vamsas Document, if it exists, or create a new one
164 * (without affecting VamsasArchive object state - so is NOT THREAD SAFE)
165 * _TODO: possibly modify internal state to lock low-level files
166 * (like the IClientDocument interface instance constructer would do)
167 * @see org.vamsas.simpleclient.VamsasArchive.getOriginalVamsasDocument for additional caveats
170 * @throws IOException
171 * @throws org.exolab.castor.xml.MarshalException
172 * @throws org.exolab.castor.xml.ValidationException
173 * ????? where does this live JBPNote ?
175 private VamsasDocument _doc=null;
178 * Create a new vamsas archive
179 * File locks are made immediately to avoid contention
181 * @param archive - file spec for new vamsas archive
182 * @param vamsasdocument true if archive is to be a fully fledged vamsas document archive
183 * @throws IOException if call to accessOriginal failed for updates, or openArchive failed.
185 public VamsasArchive(File archive, boolean vamsasdocument) throws IOException {
186 this(archive, false, vamsasdocument, null);
188 public VamsasArchive(File archive, boolean vamsasdocument, boolean overwrite) throws IOException {
189 this(archive, overwrite, vamsasdocument, null);
192 * Constructor for accessing Files under file-lock management (ie a session file)
194 * @param vamsasdocument
196 * @throws IOException
198 public VamsasArchive(VamsasFile archive, boolean vamsasdocument, boolean overwrite) throws IOException {
199 this(archive.sessionFile, overwrite, vamsasdocument, archive);
200 // log.debug("using non-functional lock-IO stream jar access constructor");
203 * read and write to archive - will not overwrite original contents, and will always write an up to date vamsas document structure.
205 * @throws IOException
207 public VamsasArchive(VamsasFile archive) throws IOException {
208 this(archive, true, false);
212 * @param archive file to write
213 * @param overwrite true if original contents should be deleted
214 * @param vamsasdocument true if a proper VamsasDocument archive is to be written.
215 * @param extantLock SessionFile object holding a lock for the <object>archive</object>
216 * @throws IOException
218 public VamsasArchive(File archive, boolean overwrite, boolean vamsasdocument, SessionFile extantLock) throws IOException {
220 if (archive==null || (archive!=null && !(archive.getAbsoluteFile().getParentFile().canWrite() && (!archive.exists() || archive.canWrite())))) {
221 log.fatal("Expect Badness! -- Invalid parameters for VamsasArchive constructor:"+((archive!=null)
222 ? "File cannot be overwritten." : "Null Object not valid constructor parameter"));
226 this.vamsasdocument = vamsasdocument;
227 if (archive.exists() && !overwrite) {
228 this.original = archive;
229 if (extantLock!=null) {
230 this.odoclock = extantLock;
231 if (odoclock.fileLock==null || !odoclock.fileLock.isLocked())
234 this.odoclock = new SessionFile(archive);
236 odoclock.lockFile(); // lock the file *immediatly*
237 this.archive = null; // archive will be a temp file when the open method is called
240 this.accessOriginal();
241 } catch (IOException e) {
242 throw new IOException("Lock failed for existing archive"+archive);
245 this.original = null;
246 this.archive = archive; // archive is written in place.
247 if (extantLock!=null)
250 rchive = new SessionFile(archive);
252 if (rchive.fileLock==null || !rchive.fileLock.isLocked())
253 throw new IOException("Lock failed for new archive"+archive);
254 rchive.fileLock.getRaFile().setLength(0); // empty the archive.
255 virginArchive = true;
257 this.openArchive(); // open archive
260 * open original archive file for exclusive (locked) reading.
261 * @throws IOException
263 private void accessOriginal() throws IOException {
264 if (original!=null && original.exists()) {
266 odoclock = new SessionFile(original);
269 odoc = new VamsasArchiveReader(original);
270 // this constructor is not implemented yet odoc = new VamsasArchiveReader(odoclock.fileLock);
275 * Add unique entry strings to internal JarEntries list.
277 * @return true if entry was unique and was added.
279 private boolean addEntry(String entry) {
281 entries=new Hashtable();
282 if (entries.containsKey(entry))
284 entries.put(entry, new Integer(entries.size()));
288 * adds named entry to newarchive or returns false.
290 * @return true if entry was unique and could be added
291 * @throws IOException if entry name was invalid or a new entry could not be made on newarchive
293 private boolean addValidEntry(String entry) throws IOException {
294 JarEntry je = new JarEntry(entry);
295 if (!addEntry(entry))
298 newarchive.putNextEntry(je);
302 * called by app to get name of backup if it was made.
303 * If this is called, the caller app *must* delete the backup themselves.
304 * @return null or a valid file object
306 public File backupFile() {
308 if (!virginArchive) {
310 donotdeletebackup=true; // external reference has been made.
311 return ((original!=null) ? originalBackup : null);
317 * Stops any current write to archive, and reverts to the backup if it exists.
318 * All existing locks on the original will be released. All backup files are removed.
320 public boolean cancelArchive() {
321 if (newarchive!=null) {
323 newarchive.closeEntry();
324 newarchive.putNextEntry(new JarEntry("deleted"));
325 newarchive.closeEntry();
328 } catch (Exception e) {
329 log.debug("Whilst closing newarchive",e);
331 if (!virginArchive) {
332 // then there is something to recover.
336 catch (Exception e) {
337 log.warn("Problems when trying to cancel Archive "+archive.getAbsolutePath(), e);
343 log.warn("Client Error: cancelArchive called before archive("+original.getAbsolutePath()+") has been opened!");
345 closeAndReset(); // tidy up and release locks.
350 * only do this if you want to destroy the current file output stream
353 private void closeAndReset() {
358 if (original!=null) {
365 if (odoclock!=null) {
366 odoclock.unlockFile();
376 * Tidies up and closes archive, removing any backups that were created.
377 * NOTE: It is up to the caller to delete the original archive backup obtained from backupFile()
378 * TODO: ensure all extant AppDataReference jar entries are transferred to new Jar
379 * TODO: provide convenient mechanism for generating new unique AppDataReferences and adding them to the document
381 public void closeArchive() throws IOException {
382 if (newarchive!=null) {
384 newarchive.closeEntry();
385 if (!isDocumentWritten())
386 log.warn("Premature closure of archive '"+archive.getAbsolutePath()+"': No document has been written.");
387 newarchive.finish();// close(); // use newarchive.finish(); for a stream IO
393 log.warn("Attempt to close archive that has not been opened for writing.");
397 * Opens and returns the applicationData output stream for the appdataReference string.
398 * @param appdataReference
399 * @return Output stream to write to
400 * @throws IOException
402 public AppDataOutputStream getAppDataStream(String appdataReference) throws IOException {
403 if (newarchive==null)
404 throw new IOException("Attempt to write to closed VamsasArchive object.");
405 if (addValidEntry(appdataReference)) {
406 return new AppDataOutputStream(newarchive);
413 * @return JarEntry name for the vamsas XML stream in this archive
415 protected String getDocumentJarEntry() {
417 return VamsasArchiveReader.VAMSASDOC;
418 return VamsasArchiveReader.VAMSASXML;
421 * Safely initializes the VAMSAS XML document Jar Entry.
422 * @return Writer to pass to the marshalling function.
423 * @throws IOException if a document entry has already been written.
425 public PrintWriter getDocumentOutputStream() throws IOException {
426 if (newarchive==null)
428 if (!isDocumentWritten()) {
430 if (addValidEntry(getDocumentJarEntry()))
431 return new PrintWriter(new java.io.OutputStreamWriter(newarchive, "UTF-8"));
432 } catch (Exception e) {
433 log.warn("Problems opening XML document JarEntry stream",e);
436 throw new IOException("Vamsas Document output stream is already written.");
442 * Access original archive if it exists, pass the reader to the client
443 * Note: this is NOT thread safe and a call to closeArchive() will by necessity
444 * close and invalidate the VamsasArchiveReader object.
445 * @return null if no original archive exists.
447 public VamsasArchiveReader getOriginalArchiveReader() throws IOException {
448 if (!virginArchive) {
455 * returns original document's root vamsas elements.
457 * @throws IOException
458 * @throws org.exolab.castor.xml.MarshalException
459 * @throws org.exolab.castor.xml.ValidationException
461 public Vobject[] getOriginalRoots() throws IOException,
462 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
463 return VamsasArchive.getOriginalRoots(this);
466 * @return original document or a new empty document (with default provenance)
467 * @throws IOException
468 * @throws org.exolab.castor.xml.MarshalException
469 * @throws org.exolab.castor.xml.ValidationException
471 public VamsasDocument getVamsasDocument() throws IOException,
472 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
473 return getVamsasDocument("org.vamsas.simpleclient.VamsasArchive", "Created new empty document", null);
476 * Return the original document or a new empty document with initial provenance entry.
477 * @param provenance_user (null sets user to be the class name)
478 * @param provenance_action (null sets action to be 'created new document')
479 * @param version (null means use latest version)
480 * @return (original document or a new vamsas document with supplied provenance and version info)
481 * @throws IOException
482 * @throws org.exolab.castor.xml.MarshalException
483 * @throws org.exolab.castor.xml.ValidationException
485 public VamsasDocument getVamsasDocument(String provenance_user, String provenance_action, String version) throws IOException,
486 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
489 _doc = getOriginalVamsasDocument(this, getVorba());
492 // validate parameters
493 if (provenance_user==null)
494 provenance_user = "org.vamsas.simpleclient.VamsasArchive";
495 if (provenance_action == null)
496 provenance_action="Created new empty document";
498 version = VersionEntries.latestVersion();
499 // Create a new document and return it
500 _doc = DocumentStuff.newVamsasDocument(new VAMSAS[] { new VAMSAS()},
501 ProvenanceStuff.newProvenance(provenance_user, provenance_action), version);
505 * @return Returns the current VorbaIdFactory for the archive.
507 public VorbaIdFactory getVorba() {
509 vorba = new SimpleDocument("simpleclient.VamsasArchive");
510 return vorba.getVorba();
513 * @return true if Vamsas Document has been written to archive
515 protected boolean isDocumentWritten() {
516 if (newarchive==null)
517 log.warn("isDocumentWritten() called for unopened archive.");
519 if (entries.containsKey(getDocumentJarEntry()))
524 private void makeBackup() {
525 if (!virginArchive) {
526 if (originalBackup==null && original!=null && original.exists()) {
529 originalBackup = odoclock.backupSessionFile(null, original.getName(), ".bak", original.getParentFile());
531 catch (IOException e) {
532 log.warn("Problem whilst making a backup of original archive.",e);
538 * opens the new archive ready for writing. If the new archive is replacing an existing one,
539 * then the existing archive will be locked, and the new archive written to a temporary file.
540 * The new archive will be put in place once close() is called.
541 * @param doclock LATER - pass existing lock on document, if it exists.... no need yet?
542 * @throws IOException
544 private void openArchive() throws IOException {
546 if (newarchive!=null) {
547 log.warn("openArchive() called multiple times.");
548 throw new IOException("Vamsas Archive '"+archive.getAbsolutePath()+"' is already open.");
550 if (archive==null && (virginArchive || original==null)) {
551 log.warn("openArchive called on uninitialised VamsasArchive object.");
552 throw new IOException("Badly initialised VamsasArchive object - no archive file specified.");
554 if (!virginArchive) {
557 // make a temporary file to write to
558 archive = File.createTempFile(original.getName(), ".new",original.getParentFile());
560 if (archive.exists())
561 log.warn("New archive file name already in use! Possible lock failure imminent?");
565 rchive = new SessionFile(archive);
566 if (!rchive.lockFile())
567 throw new IOException("Failed to get lock on file "+archive);
568 // LATER: locked IO stream based access.
569 Manifest newmanifest = new Manifest();
570 newarchive = new JarOutputStream(rchive.fileLock.getBufferedOutputStream(true), newmanifest);
571 //newarchive = new JarOutputStream(new BufferedOutputStream(new java.io.FileOutputStream(archive)));
572 entries = new Hashtable();
574 public void putVamsasDocument(VamsasDocument doc) throws IOException,
575 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
576 putVamsasDocument(doc, getVorba());
582 * @return (vorbaId string, Vobjhash) pairs for last hash of each object in document
583 * @throws IOException
584 * @throws org.exolab.castor.xml.MarshalException
585 * @throws org.exolab.castor.xml.ValidationException
587 public void putVamsasDocument(VamsasDocument doc, VorbaIdFactory vorba) throws IOException,
588 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
590 doc.setVersion(VersionEntries.latestVersion()); // LATER: ensure this does the correct thing.
591 VorbaXmlBinder.putVamsasDocument(getDocumentOutputStream(), vorba, doc);
595 * recovers the original file's contents from the (temporary) backup.
596 * @throws Exception if any SessionFile or file removal operations fail.
598 private void recoverBackup() throws Exception {
599 if (originalBackup!=null) {
600 // backup has been made.
601 // revert from backup and delete it (changing backup filename)
603 rchive = new SessionFile(original);
605 SessionFile bckup = new SessionFile(originalBackup);
607 rchive.updateFrom(null, bckup); // recover from backup file.
615 * forget about any backup that was made - removing it first if it was only temporary.
617 private void removeBackup() {
618 if (originalBackup!=null) {
619 log.debug("Removing backup in "+originalBackup.getAbsolutePath());
620 if (!donotdeletebackup)
621 if (!originalBackup.delete())
622 log.info("VamsasArchive couldn't remove temporary backup "+originalBackup.getAbsolutePath());
627 * @param vorba the VorbaIdFactory to use for accessing vamsas objects.
629 public void setVorba(VorbaIdFactory Vorba) {
632 vorba = new SimpleDocument(Vorba);
634 vorba.setVorba(Vorba);
639 * Convenience method to copy over the referred entry from the backup to the new version.
640 * Warning messages are raised if no backup exists or the
641 * entry doesn't exist in the backed-up original.
642 * Duplicate writes return true - but a warning message will also be raised.
643 * @param AppDataReference
644 * @return true if AppDataReference now exists in the new document
645 * @throws IOException
647 public boolean transferAppDataEntry(String AppDataReference) throws IOException {
648 return transferAppDataEntry(AppDataReference, AppDataReference);
651 * Validates the AppDataReference: not null and not already written to archive.
652 * @param AppDataReference
653 * @return true if valid. false if not
654 * @throws IOException for really broken references!
656 protected boolean _validNewAppDataReference(String newAppDataReference) throws IOException {
657 // LATER: Specify valid AppDataReference form in all VamsasArchive handlers
658 if (newAppDataReference==null)
659 throw new IOException("null newAppDataReference!");
660 if (entries.containsKey(newAppDataReference)) {
661 log.warn("Attempt to write '"+newAppDataReference+"' twice! - IGNORED");
662 // LATER: fix me? warning message should raise an exception here.
668 * Transfers an AppDataReference from old to new vamsas archive, with a name change.
669 * @see transferAppDataEntry(String AppDataReference)
670 * @param AppDataReference
671 * @param NewAppDataReference - AppDataReference in new Archive
673 * @throws IOException
675 public boolean transferAppDataEntry(String AppDataReference, String NewAppDataReference) throws IOException {
676 if (original==null || !original.exists()) {
677 log.warn("No backup archive exists.");
680 if (AppDataReference==null)
681 throw new IOException("null AppDataReference!");
683 if (!_validNewAppDataReference(NewAppDataReference))
688 java.io.InputStream adstream = odoc.getAppdataStream(AppDataReference);
690 if (adstream==null) {
691 log.warn("AppDataReference '"+AppDataReference+"' doesn't exist in backup archive.");
695 java.io.OutputStream adout = getAppDataStream(NewAppDataReference);
696 // copy over the bytes
699 byte[] buffer = new byte[_TRANSFER_BUFFER]; // conservative estimate of a sensible buffer
701 if ((written = adstream.read(buffer))>-1) {
702 adout.write(buffer, 0, written);
703 log.debug("Transferring "+written+".");
706 } while (written>-1);
707 log.debug("Sucessfully transferred AppData for '"
708 +AppDataReference+"' as '"+NewAppDataReference+"' ("+count+" bytes)");
712 * write data from a stream into an appData reference.
713 * @param AppDataReference - New AppDataReference not already written to archive
714 * @param adstream Source of data for appData reference - read until .read(buffer) returns -1
715 * @return true on success.
716 * @throws IOException for file IO or invalid AppDataReference string
718 public boolean writeAppdataFromStream(String AppDataReference, java.io.InputStream adstream) throws IOException {
719 if (!_validNewAppDataReference(AppDataReference)) {
720 log.warn("Invalid AppDataReference passed to writeAppdataFromStream");
721 throw new IOException("Invalid AppDataReference! (null, or maybe non-unique)!");
724 if (AppDataReference==null) {
725 log.warn("null appdata passed.");
726 throw new IOException("Null AppDataReference");
729 java.io.OutputStream adout = getAppDataStream(AppDataReference);
730 // copy over the bytes
733 byte[] buffer = new byte[_TRANSFER_BUFFER]; // conservative estimate of a sensible buffer
735 if ((written = adstream.read(buffer))>-1) {
736 adout.write(buffer, 0, written);
737 log.debug("Transferring "+written+".");
740 } while (written>-1);
744 * transfers any AppDataReferences existing in the old document
745 * that haven't already been transferred to the new one
746 * LATER: do the same for transfers requiring a namechange - more document dependent.
747 * @return true if data was transferred.
749 public boolean transferRemainingAppDatas() throws IOException {
750 boolean transfered=false;
751 if (original==null || !original.exists()) {
752 log.warn("No backup archive exists.");
757 if (getVorba()!=null) {
758 Vector originalRefs=null;
760 originalRefs = vorba.getReferencedEntries(getVamsasDocument(), getOriginalArchiveReader());
761 } catch (Exception e) {
762 log.warn("Problems accessing original document entries!",e);
764 if (originalRefs!=null) {
765 Iterator ref = originalRefs.iterator();
766 while (ref.hasNext()) {
767 String oldentry = (String) ref.next();
768 if (oldentry!=null && !entries.containsKey(oldentry)) {
769 log.debug("Transferring remaining entry '"+oldentry+"'");
770 transfered |= transferAppDataEntry(oldentry);
778 * called after archive is written to put file in its final place
780 private void updateOriginal() {
781 if (!virginArchive) {
782 // make sure original document really is backed up and then overwrite it.
784 // try to shut the odoc reader.
788 // Make a backup if it isn't done already
791 // copy new Archive data that was writen to a temporary file
792 odoclock.updateFrom(null, rchive);
794 catch (IOException e) {
795 // LATER: decide if leaving nastily named backup files around is necessary.
796 File backupFile=backupFile();
797 if (backupFile!=null)
798 log.error("Problem updating archive from temporary file! - backup left in '"
799 +backupFile().getAbsolutePath()+"'",e);
801 log.error("Problems updating, and failed to even make a backup file. Ooops!", e);
803 // Tidy up if necessary.