Merge branch 'JAL-1378_jb2.1cli' into RNAalifold
[jalview.git] / src / jalview / io / vamsas / DatastoreItem.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
3  * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, G Barton, M Clamp, S Searle
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
10  *  
11  * Jalview is distributed in the hope that it will be useful, but 
12  * WITHOUT ANY WARRANTY; without even the implied warranty 
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
14  * PURPOSE.  See the GNU General Public License for more details.
15  * 
16  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
17  */
18 package jalview.io.vamsas;
19
20 import jalview.bin.Cache;
21 import jalview.io.VamsasAppDatastore;
22
23 import java.util.Enumeration;
24 import java.util.Hashtable;
25 import java.util.IdentityHashMap;
26 import java.util.Vector;
27
28 import uk.ac.vamsas.client.IClientDocument;
29 import uk.ac.vamsas.client.Vobject;
30 import uk.ac.vamsas.client.VorbaId;
31 import uk.ac.vamsas.objects.core.Entry;
32 import uk.ac.vamsas.objects.core.Provenance;
33 import uk.ac.vamsas.objects.core.Seg;
34
35 /**
36  * Holds all the common machinery for binding objects to vamsas objects
37  * 
38  * @author JimP
39  * 
40  */
41 public abstract class DatastoreItem
42 {
43   /**
44    * 
45    */
46   Entry provEntry = null;
47
48   IClientDocument cdoc;
49
50   Hashtable vobj2jv;
51
52   IdentityHashMap jv2vobj;
53
54   boolean tojalview = false;
55
56   /**
57    * shared log instance
58    */
59   protected static org.apache.log4j.Logger log = org.apache.log4j.Logger
60           .getLogger(DatastoreItem.class);
61
62   /**
63    * note: this is taken verbatim from jalview.io.VamsasAppDatastore
64    * 
65    * @return the Vobject bound to Jalview datamodel object
66    */
67   protected Vobject getjv2vObj(Object jvobj)
68   {
69     if (jv2vobj.containsKey(jvobj))
70     {
71       return cdoc.getObject((VorbaId) jv2vobj.get(jvobj));
72     }
73     if (Cache.log.isDebugEnabled())
74     {
75       Cache.log.debug("Returning null VorbaID binding for jalview object "
76               + jvobj);
77     }
78     return null;
79   }
80
81   /**
82    * 
83    * @param vobj
84    * @return Jalview datamodel object bound to the vamsas document object
85    */
86   protected Object getvObj2jv(uk.ac.vamsas.client.Vobject vobj)
87   {
88     if (vobj2jv == null)
89       return null;
90     VorbaId id = vobj.getVorbaId();
91     if (id == null)
92     {
93       id = cdoc.registerObject(vobj);
94       Cache.log
95               .debug("Registering new object and returning null for getvObj2jv");
96       return null;
97     }
98     if (vobj2jv.containsKey(vobj.getVorbaId()))
99     {
100       return vobj2jv.get(vobj.getVorbaId());
101     }
102     return null;
103   }
104
105   /**
106    * note: this is taken verbatim from jalview.io.VamsasAppDatastore with added
107    * call to updateRegistryEntry
108    * 
109    * @param jvobj
110    * @param vobj
111    */
112   protected void bindjvvobj(Object jvobj, uk.ac.vamsas.client.Vobject vobj)
113   {
114     VorbaId id = vobj.getVorbaId();
115     if (id == null)
116     {
117       id = cdoc.registerObject(vobj);
118       if (id == null || vobj.getVorbaId() == null
119               || cdoc.getObject(id) != vobj)
120       {
121         Cache.log.error("Failed to get id for "
122                 + (vobj.isRegisterable() ? "registerable"
123                         : "unregisterable") + " object " + vobj);
124       }
125     }
126     if (vobj2jv.containsKey(vobj.getVorbaId())
127             && !(vobj2jv.get(vobj.getVorbaId())).equals(jvobj))
128     {
129       Cache.log.debug(
130               "Warning? Overwriting existing vamsas id binding for "
131                       + vobj.getVorbaId(), new Exception(
132                       "Overwriting vamsas id binding."));
133     }
134     else if (jv2vobj.containsKey(jvobj)
135             && !((VorbaId) jv2vobj.get(jvobj)).equals(vobj.getVorbaId()))
136     {
137       Cache.log.debug(
138               "Warning? Overwriting existing jalview object binding for "
139                       + jvobj, new Exception(
140                       "Overwriting jalview object binding."));
141     }
142     /*
143      * Cache.log.error("Attempt to make conflicting object binding! "+vobj+" id "
144      * +vobj.getVorbaId()+" already bound to "+getvObj2jv(vobj)+" and "+jvobj+"
145      * already bound to "+getjv2vObj(jvobj),new Exception("Excessive call to
146      * bindjvvobj")); }
147      */
148     // we just update the hash's regardless!
149     Cache.log.debug("Binding " + vobj.getVorbaId() + " to " + jvobj);
150     vobj2jv.put(vobj.getVorbaId(), jvobj);
151     // JBPNote - better implementing a hybrid invertible hash.
152     jv2vobj.put(jvobj, vobj.getVorbaId());
153     if (jvobj == this.jvobj || vobj == this.vobj)
154     {
155       updateRegistryEntry(jvobj, vobj);
156     }
157   }
158
159   /**
160    * update the vobj and jvobj references and the registry entry for this
161    * datastore object called by bindjvvobj and replacejvobjmapping
162    */
163   private void updateRegistryEntry(Object jvobj, Vobject vobj)
164   {
165     if (this.jvobj != null && this.vobj != null)
166     {
167       Cache.log.debug("updating dsobj registry. ("
168               + this.getClass().getName() + ")");
169     }
170     this.jvobj = jvobj;
171     this.vobj = vobj;
172     dsReg.registerDsObj(this);
173   }
174
175   /**
176    * replaces oldjvobject with newjvobject in the Jalview Object <> VorbaID
177    * binding tables note: originally taken verbatim from
178    * jalview.io.VamsasAppDatastore with added call to updateRegistryEntry
179    * 
180    * @param oldjvobject
181    * @param newjvobject
182    *          (may be null to forget the oldjvobject's document mapping)
183    * 
184    */
185   protected void replaceJvObjMapping(Object oldjvobject, Object newjvobject)
186   {
187     Object vobject = jv2vobj.remove(oldjvobject);
188     if (vobject == null)
189     {
190       throw new Error(
191               "IMPLEMENTATION ERROR: old jalview object is not bound ! ("
192                       + oldjvobject + ")");
193     }
194     if (newjvobject != null)
195     {
196       jv2vobj.put(newjvobject, vobject);
197       vobj2jv.put(vobject, newjvobject);
198       updateRegistryEntry(newjvobject, vobj);
199     }
200   }
201
202   public DatastoreItem()
203   {
204     super();
205   }
206
207   public DatastoreItem(VamsasAppDatastore datastore)
208   {
209     this();
210     initDatastoreItem(datastore);
211     // TODO Auto-generated constructor stub
212   }
213
214   /**
215    * construct and initialise datastore object and retrieve object bound to
216    * vobj2 and validate it against boundType
217    * 
218    * @param datastore2
219    * @param vobj2
220    * @param boundType
221    */
222   public DatastoreItem(VamsasAppDatastore datastore2, Vobject vobj2,
223           Class boundType)
224   {
225     this(datastore2);
226     vobj = vobj2;
227     jvobj = getvObj2jv(vobj2);
228     tojalview = true;
229     if (jvobj != null && !(boundType.isAssignableFrom(jvobj.getClass())))
230     {
231       throw new Error("Implementation Error: Vamsas Document Class "
232               + vobj.getClass() + " should bind to a " + boundType
233               + " (found a " + jvobj.getClass() + ")");
234     }
235     dsReg.registerDsObj(this);
236   }
237
238   /**
239    * construct and initialise datastore object and retrieve document object
240    * bound to Jalview object jvobj2 and validate it against boundType
241    * 
242    * @param datastore2
243    *          the datastore
244    * @param jvobj2
245    *          the jalview object
246    * @param boundToType
247    *          - the document object class that the bound object should be
248    *          assignable from
249    */
250   public DatastoreItem(VamsasAppDatastore datastore2, Object jvobj2,
251           Class boundToType)
252   {
253     this(datastore2);
254     jvobj = jvobj2;
255     tojalview = false;
256     vobj = getjv2vObj(jvobj);
257     if (vobj != null && !(boundToType.isAssignableFrom(vobj.getClass())))
258     {
259       throw new Error("Implementation Error: Jalview Class "
260               + jvobj2.getClass() + " should bind to a " + boundToType
261               + " (found a " + vobj.getClass() + ")");
262     }
263     dsReg.registerDsObj(this);
264   }
265
266   /**
267    * create a new vobj to be added to the document for the jalview object jvobj
268    * (jvobj!=null, vobj==null)
269    */
270   public abstract void addToDocument();
271
272   /**
273    * handle a conflict where both an existing vobj has been updated and a local
274    * jalview object has been updated. This method is only called from doSync,
275    * when an incoming update from the vamsas session conflicts with local
276    * modifications made by the Jalview user. (jvobj!=null, vobj!=null)
277    */
278   public abstract void conflict();
279
280   /**
281    * update an existing vobj in the document with the data and settings from
282    * jvobj (jvobj!=null, vobj!=null)
283    */
284   public abstract void updateToDoc();
285
286   /**
287    * update the local jalview object with the data from an existing vobj in the
288    * document (jvobj!=null, vobj!=null)
289    */
290   public abstract void updateFromDoc();
291
292   /**
293    * create a new local jvobj bound to the vobj in the document. (jvobj==null,
294    * vobj!=null)
295    */
296   public abstract void addFromDocument();
297
298   boolean addtodoc = false, conflicted = false, updated = false,
299           addfromdoc = false, success = false;
300
301   private boolean updatedtodoc;
302
303   private boolean updatedfromdoc;
304
305   /**
306    * Sync jalview to document. Enact addToDocument, conflict or update dependent
307    * on existence of a vobj bound to the local jvobj.
308    */
309   protected void doSync()
310   {
311     dsReg.registerDsObj(this);
312     if (vobj == null)
313     {
314       log.debug("adding new vobject to document.");
315       addtodoc = true;
316       addToDocument();
317     }
318     else
319     {
320       if (vobj.isUpdated())
321       {
322         log.debug("Handling update conflict for existing bound vobject.");
323         conflicted = true;
324         conflict();
325       }
326       else
327       {
328         log.debug("updating existing vobject in document.");
329         updatedtodoc = true;
330         updateToDoc();
331       }
332     }
333     // no exceptions were encountered...
334     success = true;
335   }
336
337   /**
338    * Update jalview from document. enact addFromDocument if no local jvobj
339    * exists, or update iff jvobj exists and the vobj.isUpdated() flag is set.
340    */
341   protected void doJvUpdate()
342   {
343     dsReg.registerDsObj(this);
344     if (jvobj == null)
345     {
346       log.debug("adding new vobject to Jalview from Document");
347       addfromdoc = true;
348       addFromDocument();
349     }
350     else
351     {
352       if (vobj.isUpdated())
353       {
354         log.debug("updating Jalview from existing bound vObject");
355         updatedfromdoc = true;
356         updateFromDoc();
357       }
358     }
359   }
360
361   VamsasAppDatastore datastore = null;
362
363   /**
364    * object in vamsas document
365    */
366   protected Vobject vobj = null;
367
368   /**
369    * local jalview object
370    */
371   protected Object jvobj = null;
372
373   protected DatastoreRegistry dsReg;
374
375   public void initDatastoreItem(VamsasAppDatastore ds)
376   {
377     datastore = ds;
378     dsReg = ds.getDatastoreRegisty();
379     initDatastoreItem(ds.getProvEntry(), ds.getClientDocument(),
380             ds.getVamsasObjectBinding(), ds.getJvObjectBinding());
381   }
382
383   private void initDatastoreItem(Entry provEntry, IClientDocument cdoc,
384           Hashtable vobj2jv, IdentityHashMap jv2vobj)
385   {
386     this.provEntry = provEntry;
387     this.cdoc = cdoc;
388     this.vobj2jv = vobj2jv;
389     this.jv2vobj = jv2vobj;
390   }
391
392   protected boolean isModifiable(String modifiable)
393   {
394     return modifiable == null; // TODO: USE VAMSAS LIBRARY OBJECT LOCK METHODS)
395   }
396
397   protected Vector getjv2vObjs(Vector alsq)
398   {
399     Vector vObjs = new Vector();
400     Enumeration elm = alsq.elements();
401     while (elm.hasMoreElements())
402     {
403       vObjs.addElement(getjv2vObj(elm.nextElement()));
404     }
405     return vObjs;
406   }
407
408   // utility functions
409   /**
410    * get start<end range of segment, adjusting for inclusivity flag and
411    * polarity.
412    * 
413    * @param visSeg
414    * @param ensureDirection
415    *          when true - always ensure start is less than end.
416    * @return int[] { start, end, direction} where direction==1 for range running
417    *         from end to start.
418    */
419   public int[] getSegRange(Seg visSeg, boolean ensureDirection)
420   {
421     boolean incl = visSeg.getInclusive();
422     // adjust for inclusive flag.
423     int pol = (visSeg.getStart() <= visSeg.getEnd()) ? 1 : -1; // polarity of
424     // region.
425     int start = visSeg.getStart() + (incl ? 0 : pol);
426     int end = visSeg.getEnd() + (incl ? 0 : -pol);
427     if (ensureDirection && pol == -1)
428     {
429       // jalview doesn't deal with inverted ranges, yet.
430       int t = end;
431       end = start;
432       start = t;
433     }
434     return new int[]
435     { start, end, pol < 0 ? 1 : 0 };
436   }
437
438   /**
439    * provenance bits
440    */
441   protected jalview.datamodel.Provenance getJalviewProvenance(
442           Provenance prov)
443   {
444     // TODO: fix App and Action entries and check use of provenance in jalview.
445     jalview.datamodel.Provenance jprov = new jalview.datamodel.Provenance();
446     for (int i = 0; i < prov.getEntryCount(); i++)
447     {
448       jprov.addEntry(prov.getEntry(i).getUser(), prov.getEntry(i)
449               .getAction(), prov.getEntry(i).getDate(), prov.getEntry(i)
450               .getId());
451     }
452
453     return jprov;
454   }
455
456   /**
457    * 
458    * @return default initial provenance list for a Jalview created vamsas
459    *         object.
460    */
461   Provenance dummyProvenance()
462   {
463     return dummyProvenance(null);
464   }
465
466   protected Entry dummyPEntry(String action)
467   {
468     Entry entry = new Entry();
469     entry.setApp(this.provEntry.getApp());
470     if (action != null)
471     {
472       entry.setAction(action);
473     }
474     else
475     {
476       entry.setAction("created.");
477     }
478     entry.setDate(new java.util.Date());
479     entry.setUser(this.provEntry.getUser());
480     return entry;
481   }
482
483   protected Provenance dummyProvenance(String action)
484   {
485     Provenance prov = new Provenance();
486     prov.addEntry(dummyPEntry(action));
487     return prov;
488   }
489
490   protected void addProvenance(Provenance p, String action)
491   {
492     p.addEntry(dummyPEntry(action));
493   }
494
495   /**
496    * @return true if jalview was being updated from the vamsas document
497    */
498   public boolean isTojalview()
499   {
500     return tojalview;
501   }
502
503   /**
504    * @return true if addToDocument() was called.
505    */
506   public boolean isAddtodoc()
507   {
508     return addtodoc;
509   }
510
511   /**
512    * @return true if conflict() was called
513    */
514   public boolean isConflicted()
515   {
516     return conflicted;
517   }
518
519   /**
520    * @return true if updateFromDoc() was called
521    */
522   public boolean isUpdatedFromDoc()
523   {
524     return updatedfromdoc;
525   }
526
527   /**
528    * @return true if updateToDoc() was called
529    */
530   public boolean isUpdatedToDoc()
531   {
532     return updatedtodoc;
533   }
534
535   /**
536    * @return true if addFromDocument() was called.
537    */
538   public boolean isAddfromdoc()
539   {
540     return addfromdoc;
541   }
542
543   /**
544    * @return true if object sync logic completed normally.
545    */
546   public boolean isSuccess()
547   {
548     return success;
549   }
550
551   /**
552    * @return the vobj
553    */
554   public Vobject getVobj()
555   {
556     return vobj;
557   }
558
559   /**
560    * @return the jvobj
561    */
562   public Object getJvobj()
563   {
564     return jvobj;
565   }
566
567   public boolean docWasUpdated()
568   {
569     return (this.addtodoc || this.updated) && this.success;
570   }
571
572   public boolean jvWasUpdated()
573   {
574     return (success); // TODO : Implement this properly!
575   }
576
577 }