javadoc todo
[vamsas.git] / src / uk / ac / vamsas / client / VorbaXmlBinder.java
1 /**
2  * 
3  */
4 package uk.ac.vamsas.client;
5
6 import java.io.IOException;
7 import java.io.PrintWriter;
8 import java.io.Reader;
9 import java.io.Writer;
10 import java.lang.reflect.Field;
11 import java.util.Hashtable;
12 import java.util.Iterator;
13 import java.util.Vector;
14
15 import org.apache.commons.logging.Log;
16 import org.apache.commons.logging.LogFactory;
17 import org.exolab.castor.mapping.FieldHandler;
18 import org.exolab.castor.mapping.GeneralizedFieldHandler;
19 import org.exolab.castor.mapping.ValidityException;
20 import org.exolab.castor.xml.IDResolver;
21 import org.exolab.castor.xml.MarshalException;
22 import org.exolab.castor.xml.MarshalListener;
23 import org.exolab.castor.xml.Marshaller;
24 import org.exolab.castor.xml.UnmarshalListener;
25 import org.exolab.castor.xml.Unmarshaller;
26 import org.exolab.castor.xml.ValidationException;
27
28 import uk.ac.vamsas.objects.core.VamsasDocument;
29 /**
30  * Implements the Vamsas Vobject ID machinery for translating 
31  * between non-volatile XML IDs and Vobject references. Use the
32  * marshalling and unmarshalling methods in this class in order
33  * to add automatically computed values for required fields in objects,
34  * so as to avoid validation exceptions when marshalling new objects
35  * into the vamsas document.
36  */
37 public class VorbaXmlBinder implements UnmarshalListener {
38   private static Log log = LogFactory.getLog(VorbaXmlBinder.class);
39   private final IVorbaIdFactory vorbafactory;
40
41   private final Vector obj;
42   private final Hashtable oldobjhashes;
43   private final Hashtable objrefs;
44   private final Vector updatedobjs; // not yet used elswhere ?
45   public VorbaXmlBinder(IVorbaIdFactory vorbafactory2, Vector unrefedObj, Hashtable objrefs2, Hashtable oldobjhashes, Vector updatedObj) {
46     this.vorbafactory = vorbafactory2;
47     this.obj = unrefedObj;
48     this.objrefs = objrefs2;
49     this.oldobjhashes = oldobjhashes;
50     this.updatedobjs = updatedObj;
51   }
52
53   /*
54    * (non-Javadoc)
55    * 
56    * @see org.exolab.castor.xml.UnmarshalListener#attributesProcessed(java.lang.Object)
57    */
58   public void attributesProcessed(Object object) {
59
60   }
61
62   /*
63    * (non-Javadoc)
64    * 
65    * @see org.exolab.castor.xml.UnmarshalListener#fieldAdded(java.lang.String,
66    *      java.lang.Object, java.lang.Object)
67    */
68   public void fieldAdded(String fieldName, Object parent, Object child) {
69     if (parent instanceof Vobject && child instanceof Vobject) {
70       if (((Vobject) child).V_parent==null) {
71         // System.err.println("Setting parent of "+fieldName);
72         ((Vobject) child).setV_parent((Vobject) parent);
73       }
74     }
75   }
76
77   /*
78    * (non-Javadoc)
79    * 
80    * @see org.exolab.castor.xml.UnmarshalListener#initialized(java.lang.Object)
81    */
82   public void initialized(Object object) {
83     if (object instanceof Vobject) {
84       Vobject nobj = (Vobject) object;
85     }
86   }
87
88   /*
89    * Check if the object has an 'id' field - if it does, copy the value into
90    * the VorbaId field of Vobject, and add the Vobject to the VorbaId hash.
91    * 
92    * @see org.exolab.castor.xml.UnmarshalListener#unmarshalled(java.lang.Object)
93    */
94   public void unmarshalled(Object newobj) {
95     if (newobj instanceof Vobject) {
96       Vobject nobj = (Vobject) newobj;
97       nobj.set__stored_in_document(true);
98       try {
99         if (nobj.isRegisterable() && nobj.___id_field!=null) {
100           VorbaId nobj_id=null;
101           // look for the id field (should be an NCName string)
102           nobj.__vorba = vorbafactory;
103           // use the Vobject accessor method to avoid unpleasant security exceptions.
104           String idstring = nobj.__getInstanceIdField();
105           if (idstring!=null) { 
106             if (idstring.length() > 0) {
107               nobj.setVorbaId(VorbaId.newId(idstring));
108               nobj_id=nobj.getVorbaId();
109               if (objrefs.containsKey(nobj_id) && !objrefs.get(nobj_id).equals(nobj)) {
110                 System.err.println("Serious problem : duplicate id '"+idstring+"' found! expect badness.");
111                 // TODO: HANDLE duplicate XML ids correctly
112               }
113               objrefs.put(nobj_id, nobj);
114             } else {
115               // add to list of objects without a valid vorbaId
116               obj.add(nobj);
117             }
118           } else {
119             // TODO: add to list of objects without a valid vorbaId
120             obj.add(nobj);
121           }
122           nobj.doHash(); // updates detected by comparing with last hash when marshalling
123           // check to see if new object was present in old object hash
124           if (nobj_id!=null) {
125             if (oldobjhashes.containsKey(nobj_id)) {
126               Vobjhash oldhash = (Vobjhash) oldobjhashes.get(nobj_id);
127               if (oldhash.isUpdated(nobj)) {
128                 // mark the object as updated in this document read.
129                 nobj.set__updated_since_last_read(true);
130                 updatedobjs.addElement(nobj);
131               }
132             } else {
133               // object has no entry in the oldhashvalue list but
134               // there is a valid vorbaId so
135               nobj.set__added_since_last_read(true);
136             }
137             // and record the just-unmarshalled hash value
138             oldobjhashes.put(nobj_id, new Vobjhash(nobj));
139           } else {
140             // for objects yet to get a valid vorba_id
141             nobj.set__added_since_last_read(true);
142           }
143         }
144
145       } catch (Exception e) {
146         return;
147       };
148
149     }
150   }
151
152   /**
153    * writes the VamsasDocument to the given stream.
154    * TODO: ensure that (at least) default provenance entries are written for objects.
155    * @param outstream
156    * @param vorba valid VorbaIdFactory to construct any missing IDs 
157    * @param doc
158    * @throws IOException
159    * @throws MarshalException
160    * @throws ValidationException
161    */
162   public static void putVamsasDocument(PrintWriter outstream, VorbaIdFactory vorba, VamsasDocument doc)
163   throws IOException, MarshalException, ValidationException {
164     // Ensure references
165     if (vorba==null)
166       throw new Error("Null VorbaIdFactory Parameter");
167     if (doc.__vorba==null)
168       doc.__vorba = vorba;
169     doc.__ensure_instance_ids(); // this may take a while. Do we allow for cyclic references ? 
170     doc.marshal(outstream);
171
172   }
173   /**
174    * creates new VorbaId references where necessary for newly unmarshalled objects
175    * @param unrefed
176    * @param objrefs
177    * @return false if any new object references were made
178    */
179   private static boolean ensure_references(Vector unrefed, Hashtable objrefs) {
180     boolean sync=true;
181     if (unrefed.size()>0) {
182       sync=false; // document is out of sync - ids have been created.
183       java.util.Iterator newobj = unrefed.listIterator();
184       while (newobj.hasNext()) {
185         Vobject o = (Vobject) newobj.next();
186         // forces registration and id field update.
187         VorbaId id = o.getVorbaId();
188         if (!objrefs.containsKey(id)) {
189           objrefs.put(id, o);
190         } else {
191           if (!objrefs.get(id).equals(o))
192             throw new Error("Serious! Duplicate reference made by vorbaIdFactory!");
193         }
194       }
195     }
196     return sync;
197   }
198   /**
199    * Unmarshals a vamsasDocument Vobject from a stream, registers
200    * unregistered objects, records existing VorbaIds, and completes 
201    * the uk.ac.vamsas.client.Vobject housekeeping fields.
202    * For a valid unmarshalling, the array of returned objects also includes
203    * a <return>sync</return> parameter which is true if new VorbaIds
204    * were created. If sync is false, then the caller should ensure that the
205    * vamsasDocument is written back to disk to propagate the new VorbaIds.
206    *  TODO: ensure that provenance is correct for newly registered objects
207    * as getVamsasObjects but will detect updated objects based on differing hash values
208    * obtained from the VorbaIdFactory's VorbaId, Vobject.get__last_Hash() pairs (if any) 
209    * @param instream - the XML input stream 
210    * @param factory - the SimpleClient's properly configured VorbaId factory to make new references.
211    * @param root the root element's uk.ac.vamsas.objects.core Vobject.
212    * @return null or {(Object) VamsasDocument Vobject, (Object) Hashtable of Vobject references, (Object) Boolean(sync), (Object) Vector of updated objects in document }
213    */
214   public static Object[] getVamsasObjects(Reader instream,
215       VorbaIdFactory factory, Vobject root) {  
216     Unmarshaller unmarshaller = new Unmarshaller(root);
217     unmarshaller.setIDResolver(new IDResolver() {
218       public Object resolve(String id) {
219         VorbaXmlBinder.log.warn("Warning - id " + id
220             + " is not found in the Vamsas XML!");
221         return null;
222       }
223     });
224     final Hashtable objrefs = new Hashtable();
225     if (factory.extanthashv==null)
226       factory.extanthashv=new Hashtable();
227     final Hashtable oobjhashes=factory.extanthashv;
228     final VorbaIdFactory vorbafactory = factory;
229     final Vector unrefedObj =  new Vector();
230     final Vector updatedObj = new Vector();
231     unmarshaller.setUnmarshalListener(new VorbaXmlBinder(vorbafactory, unrefedObj, objrefs, oobjhashes,updatedObj));
232     // Call the unmarshaller.
233     try {
234       while (instream.ready()) {
235         // TODO: mark objects in oobjhash prior to unmarshalling, to detect when objects have been lost through an update.
236         //tohere
237         Object obj = unmarshaller.unmarshal(instream);
238         boolean sync=ensure_references(unrefedObj, objrefs);
239         if (!(obj instanceof Vobject))
240           return null;
241         vorbafactory.setNewIdHash(objrefs); // update the Document IO Handler's set of vorbaId<>Object bindings.
242         return new Object[] { obj, objrefs, new Boolean(sync),updatedObj};
243       }
244     } catch (MarshalException e) {
245       // TODO Auto-generated catch block
246       e.printStackTrace();
247     } catch (ValidationException e) {
248       // TODO Auto-generated catch block
249       e.printStackTrace();
250     } catch (IOException e) {
251       // TODO Auto-generated catch block
252       e.printStackTrace();
253     }
254     return null;
255   }
256 }