JAL-3829 generalised Alphafold retrieval mechanism to be reused for PDBEntrys with...
[jalview.git] / src / jalview / datamodel / PDBEntry.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
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
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.datamodel;
22
23 import jalview.util.CaseInsensitiveString;
24
25 import java.util.Collections;
26 import java.util.Enumeration;
27 import java.util.Hashtable;
28
29 public class PDBEntry
30 {
31
32   /**
33    * constant for storing chain code in properties table
34    */
35   private static final String CHAIN_ID = "chain_code";
36
37   private Hashtable<String, Object> properties;
38
39   private static final int PDB_ID_LENGTH = 4;
40
41   private String file;
42
43   private String type;
44
45   private String id;
46
47   public enum Type
48   {
49     // TODO is FILE needed; if not is this enum needed, or can we
50     // use FileFormatI for PDB, MMCIF?
51     PDB("pdb", "pdb"), MMCIF("mmcif", "cif"), FILE("?", "?");
52
53     /*
54      * file extension for cached structure file; must be one that
55      * is recognised by Chimera 'open' command
56      * @see https://www.cgl.ucsf.edu/chimera/current/docs/UsersGuide/filetypes.html
57      */
58     String ext;
59
60     /*
61      * format specifier used in dbfetch request
62      * @see http://www.ebi.ac.uk/Tools/dbfetch/dbfetch/dbfetch.databases#pdb
63      */
64     String format;
65
66     private Type(String fmt, String ex)
67     {
68       format = fmt;
69       ext = ex;
70     }
71
72     public String getFormat()
73     {
74       return format;
75     }
76
77     public String getExtension()
78     {
79       return ext;
80     }
81
82     /**
83      * case insensitive matching for Type enum
84      * 
85      * @param value
86      * @return
87      */
88     public static Type getType(String value)
89     {
90       for (Type t : Type.values())
91       {
92         if (t.toString().equalsIgnoreCase(value))
93         {
94           return t;
95         }
96       }
97       return null;
98     }
99
100     /**
101      * case insensitive equivalence for strings resolving to PDBEntry type
102      * 
103      * @param t
104      * @return
105      */
106     public boolean matches(String t)
107     {
108       return (this.toString().equalsIgnoreCase(t));
109     }
110   }
111
112   /**
113    * Answers true if obj is a PDBEntry with the same id and chain code (both
114    * ignoring case), file, type and properties
115    */
116   @Override
117   public boolean equals(Object obj)
118   {
119     if (obj == null || !(obj instanceof PDBEntry))
120     {
121       return false;
122     }
123     if (obj == this)
124     {
125       return true;
126     }
127     PDBEntry o = (PDBEntry) obj;
128
129     /*
130      * note that chain code is stored as a property wrapped by a 
131      * CaseInsensitiveString, so we are in effect doing a 
132      * case-insensitive comparison of chain codes
133      */
134     boolean idMatches = id == o.id
135             || (id != null && id.equalsIgnoreCase(o.id));
136     boolean fileMatches = file == o.file
137             || (file != null && file.equals(o.file));
138     boolean typeMatches = type == o.type
139             || (type != null && type.equals(o.type));
140     if (idMatches && fileMatches && typeMatches)
141     {
142       return properties == o.properties
143               || (properties != null && properties.equals(o.properties));
144     }
145     return false;
146   }
147
148   /**
149    * Default constructor
150    */
151   public PDBEntry()
152   {
153   }
154
155   public PDBEntry(String pdbId, String chain, PDBEntry.Type type,
156           String filePath)
157   {
158     init(pdbId, chain, type, filePath);
159   }
160
161   /**
162    * @param pdbId
163    * @param chain
164    * @param entryType
165    * @param filePath
166    */
167   void init(String pdbId, String chain, PDBEntry.Type entryType,
168           String filePath)
169   {
170     this.id = pdbId;
171     this.type = entryType == null ? null : entryType.toString();
172     this.file = filePath;
173     setChainCode(chain);
174   }
175
176   /**
177    * Copy constructor.
178    * 
179    * @param entry
180    */
181   public PDBEntry(PDBEntry entry)
182   {
183     file = entry.file;
184     type = entry.type;
185     id = entry.id;
186     if (entry.properties != null)
187     {
188       properties = (Hashtable<String, Object>) entry.properties.clone();
189     }
190   }
191
192   /**
193    * Make a PDBEntry from a DBRefEntry. The accession code is used for the PDB
194    * id, but if it is 5 characters in length, the last character is removed and
195    * set as the chain code instead.
196    * 
197    * @param dbr
198    */
199   public PDBEntry(DBRefEntry dbr)
200   {
201     if (!DBRefSource.PDB.equals(dbr.getSource()))
202     {
203       throw new IllegalArgumentException(
204               "Invalid source: " + dbr.getSource());
205     }
206
207     String pdbId = dbr.getAccessionId();
208     String chainCode = null;
209     if (pdbId.length() == PDB_ID_LENGTH + 1)
210     {
211       char chain = pdbId.charAt(PDB_ID_LENGTH);
212       if (('a' <= chain && chain <= 'z') || ('A' <= chain && chain <= 'Z'))
213       {
214         pdbId = pdbId.substring(0, PDB_ID_LENGTH);
215         chainCode = String.valueOf(chain);
216       }
217     }
218     init(pdbId, chainCode, null, null);
219   }
220
221   public void setFile(String f)
222   {
223     this.file = f;
224   }
225
226   public String getFile()
227   {
228     return file;
229   }
230
231   public void setType(String t)
232   {
233     this.type = t;
234   }
235
236   public void setType(PDBEntry.Type type)
237   {
238     this.type = type == null ? null : type.toString();
239   }
240
241   public String getType()
242   {
243     return type;
244   }
245
246   public void setId(String id)
247   {
248     this.id = id;
249   }
250
251   public String getId()
252   {
253     return id;
254   }
255
256   public void setProperty(String key, Object value)
257   {
258     if (this.properties == null)
259     {
260       this.properties = new Hashtable<String, Object>();
261     }
262     properties.put(key, value);
263   }
264
265   public Object getProperty(String key)
266   {
267     return properties == null ? null : properties.get(key);
268   }
269
270   /**
271    * Returns an enumeration of the keys of this object's properties (or an empty
272    * enumeration if it has no properties)
273    * 
274    * @return
275    */
276   public Enumeration<String> getProperties()
277   {
278     if (properties == null)
279     {
280       return Collections.emptyEnumeration();
281     }
282     return properties.keys();
283   }
284
285   /**
286    * 
287    * @return null or a string for associated chain IDs
288    */
289   public String getChainCode()
290   {
291     return (properties == null || properties.get(CHAIN_ID) == null) ? null
292             : properties.get(CHAIN_ID).toString();
293   }
294
295   /**
296    * Sets a non-case-sensitive property for the given chain code. Two PDBEntry
297    * objects which differ only in the case of their chain code are considered
298    * equal. This avoids duplication of objects in lists of PDB ids.
299    * 
300    * @param chainCode
301    */
302   public void setChainCode(String chainCode)
303   {
304     if (chainCode == null)
305     {
306       deleteProperty(CHAIN_ID);
307     }
308     else
309     {
310       setProperty(CHAIN_ID, new CaseInsensitiveString(chainCode));
311     }
312   }
313
314   /**
315    * Deletes the property with the given key, and returns the deleted value (or
316    * null)
317    */
318   Object deleteProperty(String key)
319   {
320     Object result = null;
321     if (properties != null)
322     {
323       result = properties.remove(key);
324     }
325     return result;
326   }
327
328   @Override
329   public String toString()
330   {
331     return id;
332   }
333
334   /**
335    * Getter provided for Castor binding only. Application code should call
336    * getProperty() or getProperties() instead.
337    * 
338    * @deprecated
339    * @see #getProperty(String)
340    * @see #getProperties()
341    * @see jalview.ws.dbsources.Uniprot#getUniprotEntries
342    * @return
343    */
344   @Deprecated
345   public Hashtable<String, Object> getProps()
346   {
347     return properties;
348   }
349
350   /**
351    * Setter provided for Castor binding only. Application code should call
352    * setProperty() instead.
353    * 
354    * @deprecated
355    * @return
356    */
357   @Deprecated
358   public void setProps(Hashtable<String, Object> props)
359   {
360     properties = props;
361   }
362
363   /**
364    * Answers true if this object is either equivalent to, or can be 'improved'
365    * by, the given entry.
366    * <p>
367    * If newEntry has the same id (ignoring case), and doesn't have a conflicting
368    * file spec or chain code, then update this entry from its file and/or chain
369    * code.
370    * 
371    * @param newEntry
372    * @return true if modifications were made
373    */
374   public boolean updateFrom(PDBEntry newEntry)
375   {
376     if (this.equals(newEntry))
377     {
378       return true;
379     }
380
381     String newId = newEntry.getId();
382     if (newId == null || getId() == null)
383     {
384       return false; // shouldn't happen
385     }
386
387     /*
388      * id has to match (ignoring case)
389      */
390     if (!getId().equalsIgnoreCase(newId))
391     {
392       return false;
393     }
394
395     /*
396      * Don't update if associated with different structure files
397      */
398     String newFile = newEntry.getFile();
399     if (newFile != null && getFile() != null && !newFile.equals(getFile()))
400     {
401       return false;
402     }
403
404     /*
405      * Don't update if associated with different chains (ignoring case)
406      */
407     String newChain = newEntry.getChainCode();
408     if (newChain != null && newChain.length() > 0 && getChainCode() != null
409             && getChainCode().length() > 0
410             && !getChainCode().equalsIgnoreCase(newChain))
411     {
412       return false;
413     }
414
415     /*
416      * set file path if not already set
417      */
418     String newType = newEntry.getType();
419     if (getFile() == null && newFile != null)
420     {
421       setFile(newFile);
422       setType(newType);
423     }
424
425     /*
426      * set file type if new entry has it and we don't
427      * (for the case where file was not updated)
428      */
429     if (getType() == null && newType != null)
430     {
431       setType(newType);
432     }
433
434     /*
435      * set chain if not already set (we excluded differing 
436      * chains earlier) (ignoring case change only)
437      */
438     if (newChain != null && newChain.length() > 0
439             && !newChain.equalsIgnoreCase(getChainCode()))
440     {
441       setChainCode(newChain);
442     }
443
444     /*
445      * copy any new or modified properties
446      */
447     Enumeration<String> newProps = newEntry.getProperties();
448     while (newProps.hasMoreElements())
449     {
450       /*
451        * copy properties unless value matches; this defends against changing
452        * the case of chain_code which is wrapped in a CaseInsensitiveString
453        */
454       String key = newProps.nextElement();
455       Object value = newEntry.getProperty(key);
456       if (!value.equals(getProperty(key)))
457       {
458         setProperty(key, value);
459       }
460     }
461     return true;
462   }
463   
464
465   private static final String RETRIEVE_FROM="RETRIEVE_FROM";
466   /**
467    * Permanent URI for retrieving the original structure data
468    * @param urlStr
469    */
470   public void setRetrievalUrl(String urlStr)
471   {
472     setProperty(RETRIEVE_FROM, urlStr);
473   }
474   /**
475    * get the Permanent URI for retrieving the original structure data
476    */
477   public String getRetrievalUrl()
478   {
479     return (String) getProperty(RETRIEVE_FROM);
480   }
481
482   public boolean hasRetrievalUrl()
483   {
484     return (properties!=null && properties.containsKey(RETRIEVE_FROM));
485   }
486 }