1 package org.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;
19 import org.apache.commons.logging.Log;
20 import org.apache.commons.logging.LogFactory;
21 import org.vamsas.client.ClientHandle;
22 import org.vamsas.client.IVorbaIdFactory;
23 import org.vamsas.client.SessionHandle;
24 import org.vamsas.client.UserHandle;
25 import org.vamsas.client.VorbaIdFactory;
26 import org.vamsas.client.VorbaXmlBinder;
27 import org.vamsas.client.Vobject;
28 import org.vamsas.objects.core.ApplicationData;
29 import org.vamsas.objects.core.VAMSAS;
30 import org.vamsas.objects.core.VamsasDocument;
31 import org.vamsas.objects.utils.AppDataReference;
32 import org.vamsas.objects.utils.DocumentStuff;
33 import org.vamsas.objects.utils.ProvenanceStuff;
34 import org.vamsas.objects.utils.document.VersionEntries;
37 * Class for high-level io and Jar manipulation involved in creating
38 * or updating a vamsas archive (with backups).
39 * Writes to a temporary file and then swaps new file for backup.
40 * uses the sessionFile locking mechanism for safe I/O
44 public class VamsasArchive {
45 private static Log log = LogFactory.getLog(VamsasArchive.class);
47 * Access original document if it exists, and get VAMSAS root objects.
48 * @return vector of vamsas roots from original document
51 public static Vobject[] getOriginalRoots(VamsasArchive ths) throws IOException,
52 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
53 VamsasArchiveReader oReader = ths.getOriginalArchiveReader();
56 if (oReader.isValid()) {
57 InputStreamReader vdoc = new InputStreamReader(oReader.getVamsasDocumentStream());
58 VamsasDocument doc = VamsasDocument.unmarshal(vdoc);
60 return doc.getVAMSAS();
61 // TODO ensure embedded appDatas are garbage collected to save memory
63 InputStream vxmlis = oReader.getVamsasXmlStream();
64 if (vxmlis!=null) { // Might be an old vamsas file.
65 BufferedInputStream ixml = new BufferedInputStream(oReader.getVamsasXmlStream());
66 InputStreamReader vxml = new InputStreamReader(ixml);
67 VAMSAS root[] = new VAMSAS[1];
68 root[0] = VAMSAS.unmarshal(vxml);
77 * Access the original vamsas document for a VamsasArchive class, and return it.
78 * Users of the VamsasArchive class should use the getVamsasDocument method to retrieve
79 * the current document - only use this one if you want the 'backup' version.
80 * TODO: catch OutOfMemoryError - they are likely to occur here.
81 * NOTE: vamsas.xml datastreams are constructed as 'ALPHA_VERSION' vamsas documents.
83 * @return null if no document exists.
85 * @throws org.exolab.castor.xml.MarshalException
86 * @throws org.exolab.castor.xml.ValidationException
88 public static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths) throws IOException,
89 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
90 return VamsasArchive.getOriginalVamsasDocument(ths, null);
93 * Uses VorbaXmlBinder to retrieve the VamsasDocument from the original archive referred to by ths
98 * @throws org.exolab.castor.xml.MarshalException
99 * @throws org.exolab.castor.xml.ValidationException
101 public static VamsasDocument getOriginalVamsasDocument(VamsasArchive ths, VorbaIdFactory vorba) throws IOException,
102 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
103 VamsasArchiveReader oReader = ths.getOriginalArchiveReader();
106 return ths.vorba.getVamsasDocument(oReader);
108 // otherwise - there was no valid original document to read.
112 * destination of new archive data (tempfile if virginarchive=true, original archive location otherwise)
114 java.io.File archive=null;
116 * locked IO handler for new archive file
118 SessionFile rchive=null;
120 * original archive file to be updated (or null if virgin) where new data will finally reside
122 java.io.File original=null;
124 * original archive IO handler
126 SessionFile odoclock = null;
127 Lock destinationLock = null;
129 * Original archive reader class
131 VamsasArchiveReader odoc = null;
133 * true if a real vamsas document is being written.
135 boolean vamsasdocument=true;
137 * Output stream for archived data
139 JarOutputStream newarchive=null;
141 * JarEntries written to archive
143 Hashtable entries = null;
146 * true if we aren't just updating an archive
148 private boolean virginArchive=false;
151 * name of backup of existing archive that has been updated/overwritten.
152 * only one backup will be made - and this is it.
154 File originalBackup = null;
156 boolean donotdeletebackup=false;
157 private final int _TRANSFER_BUFFER=4096*4;
158 protected SimpleDocument vorba = null;
160 * LATER: ? CUT'n'Paste error ?
161 * Access and return current vamsas Document, if it exists, or create a new one
162 * (without affecting VamsasArchive object state - so is NOT THREAD SAFE)
163 * _TODO: possibly modify internal state to lock low-level files
164 * (like the IClientDocument interface instance constructer would do)
165 * @see org.vamsas.simpleclient.VamsasArchive.getOriginalVamsasDocument for additional caveats
168 * @throws IOException
169 * @throws org.exolab.castor.xml.MarshalException
170 * @throws org.exolab.castor.xml.ValidationException
171 * ????? where does this live JBPNote ?
173 private VamsasDocument _doc=null;
176 * Create a new vamsas archive
177 * File locks are made immediately to avoid contention
179 * @param archive - file spec for new vamsas archive
180 * @param vamsasdocument true if archive is to be a fully fledged vamsas document archive
181 * @throws IOException if call to accessOriginal failed for updates, or openArchive failed.
183 public VamsasArchive(File archive, boolean vamsasdocument) throws IOException {
184 this(archive, false, vamsasdocument, null);
186 public VamsasArchive(File archive, boolean vamsasdocument, boolean overwrite) throws IOException {
187 this(archive, overwrite, vamsasdocument, null);
191 * @param archive file to write
192 * @param overwrite true if original contents should be deleted
193 * @param vamsasdocument true if a proper VamsasDocument archive is to be written.
194 * @param extantLock SessionFile object holding a lock for the <object>archive</object>
195 * @throws IOException
197 public VamsasArchive(File archive, boolean overwrite, boolean vamsasdocument, SessionFile extantLock) throws IOException {
199 if (archive==null || (archive!=null && !(archive.getParentFile().canWrite() && (!archive.exists() || archive.canWrite())))) {
200 log.fatal("Expect Badness! -- Invalid parameters for VamsasArchive constructor:"+((archive!=null)
201 ? "File cannot be overwritten." : "Null Object not valid constructor parameter"));
205 this.vamsasdocument = vamsasdocument;
206 if (archive.exists() && !overwrite) {
207 this.original = archive;
208 if (extantLock!=null)
209 this.odoclock = extantLock;
211 this.odoclock = new SessionFile(archive);
212 odoclock.lockFile(); // lock the file *immediatly*
213 this.archive = null; // archive will be a temp file when the open method is called
216 this.accessOriginal();
217 } catch (IOException e) {
218 throw new IOException("Lock failed for existing archive"+archive);
221 this.original = null;
222 this.archive = archive; // archive is written in place.
223 if (extantLock!=null)
226 rchive = new SessionFile(archive);
228 if (rchive.fileLock==null || rchive.fileLock.rafile==null)
229 throw new IOException("Lock failed for new archive"+archive);
230 rchive.fileLock.rafile.setLength(0); // empty the archive.
231 virginArchive = true;
233 this.openArchive(); // open archive
236 * open original archive file for exclusive (locked) reading.
237 * @throws IOException
239 private void accessOriginal() throws IOException {
240 if (original!=null && original.exists()) {
242 odoclock = new SessionFile(original);
245 odoc = new VamsasArchiveReader(original);
250 * Add unique entry strings to internal JarEntries list.
252 * @return true if entry was unique and was added.
254 private boolean addEntry(String entry) {
256 entries=new Hashtable();
257 if (entries.containsKey(entry))
259 entries.put(entry, new Integer(entries.size()));
263 * adds named entry to newarchive or returns false.
265 * @return true if entry was unique and could be added
266 * @throws IOException if entry name was invalid or a new entry could not be made on newarchive
268 private boolean addValidEntry(String entry) throws IOException {
269 JarEntry je = new JarEntry(entry);
270 if (!addEntry(entry))
272 newarchive.putNextEntry(je);
276 * called by app to get name of backup if it was made.
277 * If this is called, the caller app *must* delete the backup themselves.
278 * @return null or a valid file object
280 public File backupFile() {
282 if (!virginArchive) {
284 donotdeletebackup=false; // external reference has been made.
285 return ((original!=null) ? originalBackup : null);
291 * Stops any current write to archive, and reverts to the backup if it exists.
292 * All existing locks on the original will be released. All backup files are removed.
294 public boolean cancelArchive() {
295 if (newarchive!=null) {
299 } catch (Exception e) {
300 log.debug("Whilst closing newarchive",e);
302 if (!virginArchive) {
303 // then there is something to recover.
307 catch (Exception e) {
308 log.warn("Problems when trying to cancel Archive "+archive.getAbsolutePath(), e);
314 log.warn("Client Error: cancelArchive called before archive("+original.getAbsolutePath()+") has been opened!");
316 closeAndReset(); // tidy up and release locks.
321 * only do this if you want to destroy the current file output stream
324 private void closeAndReset() {
329 if (original!=null) {
336 if (odoclock!=null) {
337 odoclock.unlockFile();
347 * Tidies up and closes archive, removing any backups that were created.
348 * NOTE: It is up to the caller to delete the original archive backup obtained from backupFile()
349 * TODO: ensure all extant AppDataReference jar entries are transferred to new Jar
350 * TODO: provide convenient mechanism for generating new unique AppDataReferences and adding them to the document
352 public void closeArchive() throws IOException {
353 if (newarchive!=null) {
354 newarchive.closeEntry();
355 if (!isDocumentWritten())
356 log.warn("Premature closure of archive '"+archive.getAbsolutePath()+"': No document has been written.");
361 log.warn("Attempt to close archive that has not been opened for writing.");
365 * Opens and returns the applicationData output stream for the appdataReference string.
366 * @param appdataReference
367 * @return Output stream to write to
368 * @throws IOException
370 public AppDataOutputStream getAppDataStream(String appdataReference) throws IOException {
371 if (newarchive==null)
372 throw new IOException("Attempt to write to closed VamsasArchive object.");
373 if (addValidEntry(appdataReference)) {
374 return new AppDataOutputStream(newarchive);
381 * @return JarEntry name for the vamsas XML stream in this archive
383 protected String getDocumentJarEntry() {
385 return VamsasArchiveReader.VAMSASDOC;
386 return VamsasArchiveReader.VAMSASXML;
389 * Safely initializes the VAMSAS XML document Jar Entry.
390 * @return Writer to pass to the marshalling function.
391 * @throws IOException if a document entry has already been written.
393 public PrintWriter getDocumentOutputStream() throws IOException {
394 if (newarchive==null)
396 if (!isDocumentWritten()) {
398 if (addValidEntry(getDocumentJarEntry()))
399 return new PrintWriter(new java.io.OutputStreamWriter(newarchive, "UTF-8"));
400 } catch (Exception e) {
401 log.warn("Problems opening XML document JarEntry stream",e);
404 throw new IOException("Vamsas Document output stream is already written.");
410 * Access original archive if it exists, pass the reader to the client
411 * Note: this is NOT thread safe and a call to closeArchive() will by necessity
412 * close and invalidate the VamsasArchiveReader object.
413 * @return null if no original archive exists.
415 public VamsasArchiveReader getOriginalArchiveReader() throws IOException {
416 if (!virginArchive) {
423 * returns original document's root vamsas elements.
425 * @throws IOException
426 * @throws org.exolab.castor.xml.MarshalException
427 * @throws org.exolab.castor.xml.ValidationException
429 public Vobject[] getOriginalRoots() throws IOException,
430 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
431 return VamsasArchive.getOriginalRoots(this);
434 * @return original document or a new empty document (with default provenance)
435 * @throws IOException
436 * @throws org.exolab.castor.xml.MarshalException
437 * @throws org.exolab.castor.xml.ValidationException
439 public VamsasDocument getVamsasDocument() throws IOException,
440 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
441 return getVamsasDocument("org.vamsas.simpleclient.VamsasArchive", "Created new empty document", null);
444 * Return the original document or a new empty document with initial provenance entry.
445 * @param provenance_user (null sets user to be the class name)
446 * @param provenance_action (null sets action to be 'created new document')
447 * @param version (null means use latest version)
448 * @return (original document or a new vamsas document with supplied provenance and version info)
449 * @throws IOException
450 * @throws org.exolab.castor.xml.MarshalException
451 * @throws org.exolab.castor.xml.ValidationException
453 public VamsasDocument getVamsasDocument(String provenance_user, String provenance_action, String version) throws IOException,
454 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
457 _doc = getOriginalVamsasDocument(this, getVorba());
460 // validate parameters
461 if (provenance_user==null)
462 provenance_user = "org.vamsas.simpleclient.VamsasArchive";
463 if (provenance_action == null)
464 provenance_action="Created new empty document";
466 version = VersionEntries.latestVersion();
467 // Create a new document and return it
468 _doc = DocumentStuff.newVamsasDocument(new VAMSAS[] { new VAMSAS()},
469 ProvenanceStuff.newProvenance(provenance_user, provenance_action), version);
473 * @return Returns the current VorbaIdFactory for the archive.
475 public VorbaIdFactory getVorba() {
477 vorba = new SimpleDocument("simpleclient.VamsasArchive");
478 return vorba.getVorba();
481 * @return true if Vamsas Document has been written to archive
483 protected boolean isDocumentWritten() {
484 if (newarchive==null)
485 log.warn("isDocumentWritten() called for unopened archive.");
487 if (entries.containsKey(getDocumentJarEntry()))
492 private void makeBackup() {
493 if (!virginArchive) {
494 if (originalBackup==null && original!=null && original.exists()) {
497 originalBackup = odoclock.backupSessionFile(null, original.getName(), ".bak", original.getParentFile());
499 catch (IOException e) {
500 log.warn("Problem whilst making a backup of original archive.",e);
506 * opens the new archive ready for writing. If the new archive is replacing an existing one,
507 * then the existing archive will be locked, and the new archive written to a temporary file.
508 * The new archive will be put in place once close() is called.
509 * @param doclock LATER - pass existing lock on document, if it exists.... no need yet?
510 * @throws IOException
512 private void openArchive() throws IOException {
514 if (newarchive!=null) {
515 log.warn("openArchive() called multiple times.");
516 throw new IOException("Vamsas Archive '"+archive.getAbsolutePath()+"' is already open.");
518 if (archive==null && (virginArchive || original==null)) {
519 log.warn("openArchive called on uninitialised VamsasArchive object.");
520 throw new IOException("Badly initialised VamsasArchive object - no archive file specified.");
522 if (!virginArchive) {
525 // make a temporary file to write to
526 archive = File.createTempFile(original.getName(), ".new",original.getParentFile());
528 if (archive.exists())
529 log.warn("New archive file name already in use! Possible lock failure imminent?");
533 rchive = new SessionFile(archive);
534 if (!rchive.lockFile())
535 throw new IOException("Failed to get lock on file "+archive);
536 newarchive = new JarOutputStream(new BufferedOutputStream(new java.io.FileOutputStream(archive)));
537 entries = new Hashtable();
539 public void putVamsasDocument(VamsasDocument doc) throws IOException,
540 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
541 putVamsasDocument(doc, getVorba());
544 public void putVamsasDocument(VamsasDocument doc, VorbaIdFactory vorba) throws IOException,
545 org.exolab.castor.xml.MarshalException, org.exolab.castor.xml.ValidationException {
546 VorbaXmlBinder.putVamsasDocument(getDocumentOutputStream(), vorba, doc);
550 * recovers the original file's contents from the (temporary) backup.
551 * @throws Exception if any SessionFile or file removal operations fail.
553 private void recoverBackup() throws Exception {
554 if (originalBackup!=null) {
555 // backup has been made.
556 // revert from backup and delete it (changing backup filename)
558 rchive = new SessionFile(original);
560 SessionFile bckup = new SessionFile(originalBackup);
562 rchive.updateFrom(null, bckup); // recover from backup file.
570 * forget about any backup that was made - removing it first if it was only temporary.
572 private void removeBackup() {
573 if (originalBackup!=null) {
574 log.debug("Removing backup in "+originalBackup.getAbsolutePath());
575 if (!donotdeletebackup)
576 if (!originalBackup.delete())
577 log.info("VamsasArchive couldn't remove temporary backup "+originalBackup.getAbsolutePath());
582 * @param vorba the VorbaIdFactory to use for accessing vamsas objects.
584 public void setVorba(VorbaIdFactory Vorba) {
587 vorba = new SimpleDocument(Vorba);
589 vorba.setVorba(Vorba);
594 * Convenience method to copy over the referred entry from the backup to the new version.
595 * Warning messages are raised if no backup exists or the
596 * entry doesn't exist in the backed-up original.
597 * Duplicate writes return true - but a warning message will also be raised.
598 * @param AppDataReference
599 * @return true if AppDataReference now exists in the new document
600 * @throws IOException
602 public boolean transferAppDataEntry(String AppDataReference) throws IOException {
603 return transferAppDataEntry(AppDataReference, AppDataReference);
606 * Validates the AppDataReference: not null and not already written to archive.
607 * @param AppDataReference
608 * @return true if valid. false if not
609 * @throws IOException for really broken references!
611 protected boolean _validNewAppDataReference(String newAppDataReference) throws IOException {
612 // LATER: Specify valid AppDataReference form in all VamsasArchive handlers
613 if (newAppDataReference==null)
614 throw new IOException("null newAppDataReference!");
615 if (entries.containsKey(newAppDataReference)) {
616 log.warn("Attempt to write '"+newAppDataReference+"' twice! - IGNORED");
617 // LATER: fix me? warning message should raise an exception here.
623 * Transfers an AppDataReference from old to new vamsas archive, with a name change.
624 * @see transferAppDataEntry(String AppDataReference)
625 * @param AppDataReference
626 * @param NewAppDataReference - AppDataReference in new Archive
628 * @throws IOException
630 public boolean transferAppDataEntry(String AppDataReference, String NewAppDataReference) throws IOException {
631 if (original==null || !original.exists()) {
632 log.warn("No backup archive exists.");
635 if (AppDataReference==null)
636 throw new IOException("null AppDataReference!");
638 if (!_validNewAppDataReference(NewAppDataReference))
643 java.io.InputStream adstream = odoc.getAppdataStream(AppDataReference);
645 if (adstream==null) {
646 log.warn("AppDataReference '"+AppDataReference+"' doesn't exist in backup archive.");
650 java.io.OutputStream adout = getAppDataStream(NewAppDataReference);
651 // copy over the bytes
654 byte[] buffer = new byte[_TRANSFER_BUFFER]; // conservative estimate of a sensible buffer
656 if ((written = adstream.read(buffer))>-1) {
657 adout.write(buffer, 0, written);
658 log.debug("Transferring "+written+".");
661 } while (written>-1);
662 log.debug("Sucessfully transferred AppData for '"
663 +AppDataReference+"' as '"+NewAppDataReference+"' ("+count+" bytes)");
667 * write data from a stream into an appData reference.
668 * @param AppDataReference - New AppDataReference not already written to archive
669 * @param adstream Source of data for appData reference - read until .read(buffer) returns -1
670 * @return true on success.
671 * @throws IOException for file IO or invalid AppDataReference string
673 public boolean writeAppdataFromStream(String AppDataReference, java.io.InputStream adstream) throws IOException {
674 if (!_validNewAppDataReference(AppDataReference)) {
675 log.warn("Invalid AppDataReference passed to writeAppdataFromStream");
676 throw new IOException("Invalid AppDataReference! (null, or maybe non-unique)!");
679 if (AppDataReference==null) {
680 log.warn("null appdata passed.");
681 throw new IOException("Null AppDataReference");
684 java.io.OutputStream adout = getAppDataStream(AppDataReference);
685 // copy over the bytes
688 byte[] buffer = new byte[_TRANSFER_BUFFER]; // conservative estimate of a sensible buffer
690 if ((written = adstream.read(buffer))>-1) {
691 adout.write(buffer, 0, written);
692 log.debug("Transferring "+written+".");
695 } while (written>-1);
699 * transfers any AppDataReferences existing in the old document
700 * that haven't already been transferred to the new one
701 * LATER: do the same for transfers requiring a namechange - more document dependent.
702 * @return true if data was transferred.
704 public boolean transferRemainingAppDatas() throws IOException {
705 boolean transfered=false;
706 if (original==null || !original.exists()) {
707 log.warn("No backup archive exists.");
712 if (getVorba()!=null) {
713 Vector originalRefs=null;
715 originalRefs = vorba.getReferencedEntries(getVamsasDocument(), getOriginalArchiveReader());
716 } catch (Exception e) {
717 log.warn("Problems accessing original document entries!",e);
719 if (originalRefs!=null) {
720 Iterator ref = originalRefs.iterator();
721 while (ref.hasNext()) {
722 String oldentry = (String) ref.next();
723 if (oldentry!=null && !entries.containsKey(oldentry)) {
724 log.debug("Transferring remaining entry '"+oldentry+"'");
725 transfered |= transferAppDataEntry(oldentry);
733 * called after archive is written to put file in its final place
735 private void updateOriginal() {
736 if (!virginArchive) {
737 // make sure original document really is backed up and then overwrite it.
739 // try to shut the odoc reader.
743 // Make a backup if it isn't done already
746 // copy new Archive data that was writen to a temporary file
747 odoclock.updateFrom(null, rchive);
749 catch (IOException e) {
750 // LATER: decide if leaving nastily named backup files around is necessary.
751 log.error("Problem updating archive from temporary file! - backup left in '"
752 +backupFile().getAbsolutePath()+"'",e);
754 // Tidy up if necessary.