2 * This file is part of the Vamsas Client version 0.1.
3 * Copyright 2009 by Jim Procter, Iain Milne, Pierre Marguerite,
4 * Andrew Waterhouse and Dominik Lindner.
6 * Earlier versions have also been incorporated into Jalview version 2.4
7 * since 2008, and TOPALi version 2 since 2007.
9 * The Vamsas Client is free software: you can redistribute it and/or modify
10 * it under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation, either version 3 of the License, or
12 * (at your option) any later version.
14 * The Vamsas Client is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with the Vamsas Client. If not, see <http://www.gnu.org/licenses/>.
22 package uk.ac.vamsas.client.simpleclient;
24 import java.io.IOException;
25 import java.util.Vector;
27 import org.apache.commons.logging.Log;
28 import org.apache.commons.logging.LogFactory;
30 import uk.ac.vamsas.client.ClientHandle;
31 import uk.ac.vamsas.client.IClientAppdata;
32 import uk.ac.vamsas.client.IClientDocument;
33 import uk.ac.vamsas.client.UserHandle;
34 import uk.ac.vamsas.client.Vobject;
35 import uk.ac.vamsas.client.VorbaId;
36 import uk.ac.vamsas.objects.core.ApplicationData;
37 import uk.ac.vamsas.objects.core.User;
38 import uk.ac.vamsas.objects.core.VAMSAS;
39 import uk.ac.vamsas.objects.core.VamsasDocument;
40 import uk.ac.vamsas.objects.utils.AppDataReference;
41 import uk.ac.vamsas.test.objects.Core;
44 * Maintains a collection of vamsas objects, appdatas and states, and provides
45 * api for a SimpleClient's client. TODO: test and migrate
46 * ArchiveClient.getAppData methods to here and retest in ExampleApplication
50 public class ClientDocument extends uk.ac.vamsas.client.ClientDocument
51 implements IClientDocument {
52 private static Log log = LogFactory.getLog(ClientDocument.class);
54 private VamsasDocument doc;
56 protected SimpleClient sclient;
58 protected VamsasArchive iohandler = null;
61 * indicate if new data has been incorporated
63 private boolean isModified = false;
66 * Public method for internal use by SimpleClient.
68 * @return true if document has been modified.
70 public boolean isModified() {
76 * prepare Application-side dataset from the vamsas Document iohandler
81 * - the sessionFile IO handler
83 * - the source of current and new vorbaIds
85 * - the simpleclient instance
87 protected ClientDocument(VamsasDocument doc, VamsasArchive docHandler,
88 IdFactory Factory, SimpleClient sclient) {
89 super(Factory.getVorbaIdHash(), Factory);
92 * prepare Application-side dataset from the vamsas Document iohandler
94 this.sclient = sclient;
95 iohandler = docHandler;
97 _VamsasRoots = doc.getVAMSAS();
104 * uk.ac.vamsas.client.IClientDocument#getObject(uk.ac.vamsas.client.VorbaId)
106 public Vobject getObject(VorbaId id) {
107 if (vamsasObjects == null) {
108 log.debug("getObject called on null objrefs list.");
111 if (vamsasObjects.containsKey(id))
112 return (Vobject) vamsasObjects.get(id);
113 log.debug("Returning null Vobject reference for id " + id.getId());
121 * uk.ac.vamsas.client.IClientDocument#getObjects(uk.ac.vamsas.client.VorbaId
124 public Vobject[] getObjects(VorbaId[] ids) {
125 if (vamsasObjects == null) {
126 log.debug("getObject[] called on null vamsasObjects list.");
129 Vobject[] vo = new Vobject[ids.length];
130 for (int i = 0, j = ids.length; i < j; i++)
131 if (vamsasObjects.containsKey(ids[i]))
132 vo[i] = (Vobject) vamsasObjects.get(ids[i]);
134 log.debug("Returning null Vobject reference for id " + ids[i].getId());
139 * internal reference to single copy of Document Roots array
141 private VAMSAS[] _VamsasRoots = null;
144 * set if the client has corrupted the Vamsas Document structure somehow. if
145 * this is set the document will never be written back to the session unless
146 * the corruption is fixed.
148 private boolean invalidModification = false;
150 protected void updateDocumentRoots() {
153 .error("updateDocumentRoots called on null document. Probably an implementation error.");
157 if (_VamsasRoots != null) {
158 doc.setVAMSAS(_VamsasRoots);
165 * (non-Javadoc) LATER: currently there is only one Vector of roots ever
166 * passed to client - decide if this is correct (means this is not thread safe
167 * and may behave unexpectedly)
169 * @see uk.ac.vamsas.client.IClientDocument#getVamsasRoots()
171 public VAMSAS[] getVamsasRoots() {
173 log.debug("Null document for getVamsasRoots(), returning null");
176 if (iohandler == null) {
177 // LATER: decide on read-only status of ClientDocument object
178 log.warn("getVamsasRoots() called on possibly read-only document.");
180 if (_VamsasRoots != null)
182 VAMSAS[] roots = doc.getVAMSAS();
184 // Make a new one to return to client to get filled.
185 _VamsasRoots = new VAMSAS[] { new VAMSAS() };
186 registerObject(_VamsasRoots[0]);
187 // Do provenance now. just in case.
188 doc.getProvenance().addEntry(
189 sclient.getProvenanceEntry("Created new document root [id="
190 + _VamsasRoots[0].getId() + "]"));
191 doc.addVAMSAS(_VamsasRoots[0]);
193 _VamsasRoots = new VAMSAS[roots.length];
194 for (int r = 0; r < roots.length; r++)
195 _VamsasRoots[r] = roots[r];
200 private int _contains(VAMSAS root, VAMSAS[] docRoots) {
203 if (docRoots == null || docRoots.length == 0)
205 VorbaId d_id = null, r_id = root.getVorbaId();
206 for (int i = 0, j = docRoots.length; i < j; i++)
207 if (docRoots[i] == root
208 || (docRoots[i] != null && (d_id = docRoots[i].getVorbaId()) != null)
209 && d_id.equals(r_id))
215 * verify that newr version is really an intact version of the
221 * @return true if newVersion is a valid root that preserves original
224 private boolean isValidUpdate(VAMSAS newVersion, final VAMSAS oldVersion,
225 ClientDocument modflag) {
226 // ideal - this cascades down the two structures, ensuring that all ID'd
227 // objects in one are present in the other.
228 if (oldVersion == newVersion) {
229 // may be a virgin root element.
230 if (!newVersion.isRegistered()) {
231 _registerObject(newVersion); // TODO: check - this call hasn't been
232 // tested. (seems to work now)
233 modflag.isModified = true;
235 // TODO: Should attempt to repair document if client app has
236 // deleted/broken bits of it
237 if (oldVersion.is__stored_in_document()) {
238 // retrieve compare hashCodes to detect update.
239 if (oldVersion.get__last_hash() != oldVersion.hashCode()) {
240 log.debug("Modified hashcode for vamsas root "
241 + oldVersion.getVorbaId());
242 modflag.isModified = true;
244 log.debug("Unmodified vamsas root " + oldVersion.getVorbaId());
247 // just do internal validation for moment.
249 if (getSimpleClientConfig().validateUpdatedRoots()) {
250 newVersion.validate();
253 } catch (Exception e) {
254 log.error("Validation Exception for new vamsas root :"
255 + newVersion.getVorbaId(), e);
256 modflag.invalidModification = true;
260 // redundant ? if (oldVersion.is__stored_in_document())
261 if (!newVersion.isRegistered()) {
262 _registerObject(newVersion);
263 modflag.isModified = true;
266 if (getSimpleClientConfig().validateMergedRoots()) {
267 newVersion.validate();
269 modflag.isModified = true;
271 } catch (Exception e) {
272 log.error("Validation Exception for new vamsas root :"
273 + newVersion.getVorbaId(), e);
278 * LATER: MUCH LATER! - not needed for simple case and this routine
279 * shouldn't live in this class anymore isValidUpdate : Ideally. we
280 * efficiently walk down, comparing hashes, to deal with merging and
281 * verifying provenance for objects
283 * // extract root objects if (newroots != null) { // check newroots for
284 * objects that were present in the old document // check to see if the
285 * 'old' objects have been modified // if they have ? we overwrite them with
286 * their new version, ensuring that // provenance is updated. // if they
287 * haven't ? do nothing ?
289 * for (int i = 0, k = newroots.length; i < k; i++) { if
290 * (newroots[i].isRegistered()) { // easy - just check if anything has
291 * changed and do provenance Vobject oldversion =
292 * getObject(newroots[i].getVorbaId()); if (oldversion instanceof VAMSAS) {
293 * // LATER: appropriate merging behaviour when two clients have improperly
294 * modified the same Vobject independently. if (newroots[i].get__last_hash()
295 * != newroots[i].hashCode()) { // client has modified this Vobject since
296 * last retrieval. if (newroots[i].get__last_hash() !=
297 * oldversion.get__last_hash()) { // Vobject has been modified by another
298 * client since this // client's // last access to document. } } } else {
300 * "SimpleClient error when using setVamsasRoots : The vorbaId for Vobject "
302 * " does not refer to an Vobject of type VAMSAS in the current document!");
303 * } } else { if (!newroots[i].is__stored_in_document()) { // check if
304 * Vobject is modified if (newroots[i].get__last_hash() !=
305 * newroots[i].hashCode()) { // it is - so we add newroots[i] as a new
306 * Vobject, with updated // provenance. } else { // do nothing newroots[i] =
307 * null; } } else { // just add newroots[i] as a new Vobject in the document
308 * // - with appropriate provenance. } } }
312 private SimpleClientConfig getSimpleClientConfig() {
313 return sclient.getSimpleClientConfig();
317 * merge old and new root vectors
320 * This array may be written to
323 * client document (usually this) which this root set belongs to.
324 * @return merged vector of vamsas roots
326 private VAMSAS[] _combineRoots(VAMSAS[] newr, final VAMSAS[] original,
327 ClientDocument modflag) {
328 Vector rts = new Vector();
329 for (int i = 0, j = original.length; i < j; i++) {
330 int k = _contains(original[i], newr);
332 if (isValidUpdate(newr[k], original[i], modflag)) {
333 // set by isValidUpdate if the hashcodes were really different from
338 // LATER: try harder to merge ducument roots.
339 log.warn("Couldn't merge new VAMSAS root " + newr[k].getId());
340 newr[k] = null; // LATER: this means we ignore mangled roots. NOT GOOD
344 rts.add(original[i]);
347 // add remaining (new) roots
348 for (int i = 0, j = newr.length; i < j; i++) {
349 if (newr[i] != null) {
351 modflag.isModified = true;
354 newr = new VAMSAS[rts.size()];
355 for (int i = 0, j = rts.size(); i < j; i++)
356 newr[i] = (VAMSAS) rts.get(i);
361 * update the document with new roots. LATER: decide: this affects the next
362 * call to getVamsasRoots()
364 * @see org.vamsas.IClientDocument.setVamsasRoots
366 public void setVamsasRoots(VAMSAS[] newroots) {
368 log.debug("setVamsasRoots called on null document.");
372 if (newroots == null) {
373 log.debug("setVamsasRoots(null) - do nothing.");
376 // are we dealing with same array ?
377 if (_VamsasRoots != newroots) {
378 // merge roots into local version.
379 newr = new VAMSAS[newroots.length];
380 for (int i = 0; i < newr.length; i++)
381 newr[i] = newroots[i];
382 newr = _combineRoots(newr, _VamsasRoots, this);
384 newr = new VAMSAS[_VamsasRoots.length];
385 for (int i = 0; i < newr.length; i++)
386 newr[i] = _VamsasRoots[i];
388 // actually compare with document root set for final combination (to ensure
390 _VamsasRoots = _combineRoots(newr, doc.getVAMSAS(), this);
394 * (non-Javadoc) LATER: decide: this affects the next call to getVamsasRoots()
397 * uk.ac.vamsas.client.IClientDocument#addVamsasRoot(uk.ac.vamsas.objects.
400 public void addVamsasRoot(VAMSAS newroot) {
402 log.debug("addVamsasRoots called on null document.");
405 VAMSAS[] newroots = _combineRoots(new VAMSAS[] { newroot },
406 getVamsasRoots(), this);
407 _VamsasRoots = newroots;
414 * uk.ac.vamsas.client.IClientDocument#registerObjects(uk.ac.vamsas.client
417 public VorbaId[] registerObjects(Vobject[] unregistered) {
419 log.warn("registerObjects[] called on null document.");
422 if (vamsasObjects == null) {
423 log.warn("registerObjects[] called for null vamsasObjects hasharray.");
426 if (unregistered != null) {
427 VorbaId ids[] = new VorbaId[unregistered.length];
428 for (int i = 0, k = unregistered.length; i < k; i++)
429 if (unregistered[i] != null) {
430 log.warn("Null Vobject passed to registerObject[] at position " + i);
433 ids[i] = registerObject(unregistered[i]);
435 log.debug("Registered " + unregistered.length + " objects - total of "
436 + vamsasObjects.size() + " ids.");
446 * uk.ac.vamsas.client.IClientDocument#registerObject(uk.ac.vamsas.client.
449 public VorbaId registerObject(Vobject unregistered) {
451 log.warn("registerObjects called on null document.");
454 if (vamsasObjects == null) {
455 log.warn("registerObjects called for null vamsasObjects hasharray.");
458 if (iohandler == null) {
459 log.warn("registerObjects called for read only document.");
463 if (unregistered != null) {
464 VorbaId id = _registerObject(unregistered);
465 log.debug("Registered object - total of " + vamsasObjects.size()
469 log.warn("Null Vobject passed to registerObject.");
474 * IClientAppdata instance - if it exists.
476 SimpleClientAppdata scappd = null;
481 * @see uk.ac.vamsas.client.IClientDocument#getClientAppdata()
483 public IClientAppdata getClientAppdata() {
484 // TODO: getClientAppdata not tested in ArchiveClient mockup
485 log.error("TODO: TEST Client Appdata access methods");
487 log.warn("getClientAppdata called on null document.");
490 if (scappd == null) {
491 log.debug("Creating new SimpleClientAppdata instance for "
492 + sclient.getSessionHandle());
493 scappd = new SimpleClientAppdata(this);
494 if (scappd == null) {
495 // LATER: may not need this as a warning message.
496 log.warn("Null appdata object for " + sclient.getSessionHandle());
498 log.debug("Created SimpleClientAppdata successfully.");
501 log.debug("Returning existing SimpleClientAppdata reference.");
507 * access the vamsas document
509 * @return the session's vamsas document
511 protected VamsasDocument getVamsasDocument() {
516 * returns the read-only IO interface for the vamsas document Jar file
520 protected VamsasArchiveReader getVamsasArchiveReader() {
521 if (iohandler == null) {
523 .error("Near fatal. Null VamsasArchive iohandler so can't get VamsasArchiveReader");
527 log.info("TODO: test getVamsasArchiveReader");
528 return iohandler.getOriginalArchiveReader();
529 } catch (Exception e) {
530 log.warn("Unable to create OriginalArchiveReader!", e);
536 * called by vamsas api to write updated document to session
538 * @return true if update was successful
539 * @throws java.io.IOException
541 protected boolean updateSessionDocument() throws java.io.IOException {
542 boolean docupdate = true; // 'non-serious' problems below set this false
544 log.warn("updateSessionDocument called on null document.");
545 throw new java.io.IOException("Document is closed.");
547 if (iohandler == null) {
549 .warn("updateSessionDocument called on null document iohandler handler.");
550 throw new java.io.IOException("Document is closed.");
553 if (!isModified() && !scappd.isModified()) {
554 log.debug("Document update not necessary. returning false.");
557 VamsasSession session = sclient._session;
558 log.debug("updating Session Document in " + session.sessionDir);
559 // update the VamsasDocument structure with any new appData's.
560 // try to update the sessionFile
562 .debug("Attempting to update session "
563 + sclient.session.getSessionUrn());
564 if (scappd != null && scappd.isModified()) {
565 ClientHandle client = sclient.client;
566 UserHandle user = sclient.user;
567 scappd.closeForWriting();
568 if (scappd.appsGlobal == null) {
569 log.debug("Creating new appData entry for this application...");
570 // first write for this application - add a new section in document
571 ApplicationData appd = scappd.appsGlobal = new ApplicationData();
572 appd.setName(client.getClientName());
573 // appd.setUrn(client.getClientUrn());
574 appd.setVersion(client.getVersion());
575 doc.addApplicationData(appd);
576 // embed or jarEntry ? - for now only jarEntry's are dealt with.
577 appd.setDataReference(AppDataReference.uniqueAppDataReference(doc,
578 sclient.client.getClientUrn()));
579 log.debug("... created.");
581 if (scappd.newAppData != null && scappd.newAppData.sessionFile.exists()) {
582 log.debug("Beginning update for new Global Appdata...");
583 // new global appdata to write.
584 if (scappd.appsGlobal.getData() != null) {
585 scappd.appsGlobal.setData(null);
586 scappd.appsGlobal.setDataReference(AppDataReference
587 .uniqueAppDataReference(doc, sclient.client.getClientUrn()));
589 // LATER: use a switch to decide if the data should be written as a
590 // reference or as an embedded data chunk
591 scappd.updateAnAppdataEntry(iohandler, scappd.appsGlobal,
593 log.debug("...Successfully updated Global Appdata Entry.");
595 if (scappd.newUserData != null && scappd.newUserData.sessionFile.exists()) {
596 log.debug("Beginning to update Users Appdata entry....");
597 if (scappd.usersData == null) {
598 // create new user appdata
599 scappd.usersData = new User();
600 scappd.usersData.setFullname(user.getFullName());
601 scappd.usersData.setOrganization(user.getOrganization());
602 scappd.appsGlobal.addUser(scappd.usersData);
604 User appd = scappd.usersData;
605 if (appd.getData() != null || appd.getDataReference() == null) {
606 // LATER make standard appDataReference constructor for client+user
608 String safe_username = user.getFullName();
609 int t = safe_username.indexOf(" ");
611 safe_username = safe_username.substring(t);
613 appd.setDataReference(AppDataReference.uniqueAppDataReference(doc,
614 sclient.client.getClientUrn() + safe_username));
616 scappd.updateAnAppdataEntry(iohandler, scappd.usersData,
618 log.debug("...Successfully updated user AppData entry.");
622 if (iohandler.transferRemainingAppDatas())
623 log.debug("Remaining appdatas were transferred.");
625 log.debug("No remaining appdatas were transferred. (Correct?)");
626 } catch (Exception e) {
627 log.error("While transferring remaining AppDatas", e);
629 log.debug("Updating Document...");
630 // now update the document. - this was basically the doUpdate method in
631 // test.ArchiveClient
632 updateDocumentRoots();
634 iohandler.putVamsasDocument(doc);
635 log.debug("Successfully written document entry.");
636 } catch (Exception e) {
637 log.error("Marshalling error for vamsas document.", e);
638 docupdate = false; // pass on the (probable) object validation error
640 iohandler.closeArchive();
641 iohandler = null; // so this method cannot be called again for this instance
642 log.debug("...successully finished and closed.");
643 return docupdate; // no errors ?
649 * @see java.lang.Object#finalize()
651 protected void finalize() throws Throwable {
652 log.debug("Garbage collecting on ClientDocument instance.");
653 if (scappd != null) {
660 // disengage from client
661 if (sclient != null && sclient.cdocument == this)
662 sclient.cdocument = null;
668 public Vector getUpdatedObjects() {
669 // TODO: WALK through the document objects calling the update mechanism for
670 // each one, or just pass this vector back to client ?return updatedObjects;
675 * if this is set the document will never be written back to the session
676 * unless the corruption is fixed.
678 * @return the invalidModification
680 public boolean isInvalidModification() {
681 return invalidModification;
685 * set if the client has corrupted the Vamsas Document structure somehow. if
686 * this is set the document will never be written back to the session unless
687 * the corruption is fixed.
689 * @param invalidModification
690 * the invalidModification to set
692 public void setInvalidModification(boolean invalidModification) {
693 this.invalidModification = invalidModification;