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     PDB, MMCIF, FILE;
  50     /**
  51      * case insensitive matching for Type enum
  52      *
  53      * @param value
  54      * @return
  55      */
  56     public static Type getType(String value)
  57     {
  58       for (Type t : Type.values())
  59       {
  60         if (t.toString().equalsIgnoreCase(value))
  61         {
  62           return t;
  63         }
  64       }
  65       return null;
  66     }
  67
  68     /**
  69      * case insensitive equivalence for strings resolving to PDBEntry type
  70      *
  71      * @param t
  72      * @return
  73      */
  74     public boolean matches(String t)
  75     {
  76       return (this.toString().equalsIgnoreCase(t));
  77     }
  78   }
  79
  80
  81   /**
  82    * Answers true if obj is a PDBEntry with the same id and chain code (both
  83    * ignoring case), file, type and properties
  84    */
  85   @Override
  86   public boolean equals(Object obj)
  87   {
  88     if (obj == null || !(obj instanceof PDBEntry))
  89     {
  90       return false;
  91     }
  92     if (obj == this)
  93     {
  94       return true;
  95     }
  96     PDBEntry o = (PDBEntry) obj;
  97
  98     /*
  99      * note that chain code is stored as a property wrapped by a
 100      * CaseInsensitiveString, so we are in effect doing a
 101      * case-insensitive comparison of chain codes
 102      */
 103     boolean idMatches = id == o.id
 104             || (id != null && id.equalsIgnoreCase(o.id));
 105     boolean fileMatches = file == o.file
 106             || (file != null && file.equals(o.file));
 107     boolean typeMatches = type == o.type
 108             || (type != null && type.equals(o.type));
 109     if (idMatches && fileMatches && typeMatches)
 110     {
 111       return properties == o.properties
 112               || (properties != null && properties.equals(o.properties));
 113     }
 114     return false;
 115   }
 116
 117   /**
 118    * Default constructor
 119    */
 120   public PDBEntry()
 121   {
 122   }
 123
 124
 125   public PDBEntry(String pdbId, String chain, PDBEntry.Type type,
 126           String filePath)
 127   {
 128     init(pdbId, chain, type, filePath);
 129   }
 130
 131   /**
 132    * @param pdbId
 133    * @param chain
 134    * @param entryType
 135    * @param filePath
 136    */
 137   void init(String pdbId, String chain, PDBEntry.Type entryType, String filePath)
 138   {
 139     this.id = pdbId;
 140     this.type = entryType == null ? null : entryType.toString();
 141     this.file = filePath;
 142     setChainCode(chain);
 143   }
 144
 145   /**
 146    * Copy constructor.
 147    *
 148    * @param entry
 149    */
 150   public PDBEntry(PDBEntry entry)
 151   {
 152     file = entry.file;
 153     type = entry.type;
 154     id = entry.id;
 155     if (entry.properties != null)
 156     {
 157       properties = (Hashtable<String, Object>) entry.properties.clone();
 158     }
 159   }
 160
 161   /**
 162    * Make a PDBEntry from a DBRefEntry. The accession code is used for the PDB
 163    * id, but if it is 5 characters in length, the last character is removed and
 164    * set as the chain code instead.
 165    *
 166    * @param dbr
 167    */
 168   public PDBEntry(DBRefEntry dbr)
 169   {
 170     if (!DBRefSource.PDB.equals(dbr.getSource()))
 171     {
 172       throw new IllegalArgumentException("Invalid source: "
 173               + dbr.getSource());
 174     }
 175
 176     String pdbId = dbr.getAccessionId();
 177     String chainCode = null;
 178     if (pdbId.length() == PDB_ID_LENGTH + 1)
 179     {
 180       char chain = pdbId.charAt(PDB_ID_LENGTH);
 181       if (('a' <= chain && chain <= 'z') || ('A' <= chain && chain <= 'Z'))
 182       {
 183         pdbId = pdbId.substring(0, PDB_ID_LENGTH);
 184         chainCode = String.valueOf(chain);
 185       }
 186     }
 187     init(pdbId, chainCode, null, null);
 188   }
 189
 190   public void setFile(String f)
 191   {
 192     this.file = f;
 193   }
 194
 195   public String getFile()
 196   {
 197     return file;
 198   }
 199
 200   public void setType(String t)
 201   {
 202     this.type = t;
 203   }
 204
 205   public void setType(PDBEntry.Type type)
 206   {
 207     this.type = type == null ? null : type.toString();
 208   }
 209
 210   public String getType()
 211   {
 212     return type;
 213   }
 214
 215   public void setId(String id)
 216   {
 217     this.id = id;
 218   }
 219
 220   public String getId()
 221   {
 222     return id;
 223   }
 224
 225   public void setProperty(String key, Object value)
 226   {
 227     if (this.properties == null)
 228     {
 229       this.properties = new Hashtable<String, Object>();
 230     }
 231     properties.put(key, value);
 232   }
 233
 234   public Object getProperty(String key)
 235   {
 236     return properties == null ? null : properties.get(key);
 237   }
 238
 239   /**
 240    * Returns an enumeration of the keys of this object's properties (or an empty
 241    * enumeration if it has no properties)
 242    *
 243    * @return
 244    */
 245   public Enumeration<String> getProperties()
 246   {
 247     if (properties == null)
 248     {
 249       return Collections.emptyEnumeration();
 250     }
 251     return properties.keys();
 252   }
 253
 254   /**
 255    *
 256    * @return null or a string for associated chain IDs
 257    */
 258   public String getChainCode()
 259   {
 260     return (properties == null || properties.get(CHAIN_ID) == null) ? null
 261             : properties.get(CHAIN_ID).toString();
 262   }
 263
 264   /**
 265    * Sets a non-case-sensitive property for the given chain code. Two PDBEntry
 266    * objects which differ only in the case of their chain code are considered
 267    * equal. This avoids duplication of objects in lists of PDB ids.
 268    *
 269    * @param chainCode
 270    */
 271   public void setChainCode(String chainCode)
 272   {
 273     if (chainCode == null)
 274     {
 275       deleteProperty(CHAIN_ID);
 276     }
 277     else
 278     {
 279       setProperty(CHAIN_ID, new CaseInsensitiveString(chainCode));
 280     }
 281   }
 282
 283   /**
 284    * Deletes the property with the given key, and returns the deleted value (or
 285    * null)
 286    */
 287   Object deleteProperty(String key)
 288   {
 289     Object result = null;
 290     if (properties != null)
 291     {
 292       result = properties.remove(key);
 293     }
 294     return result;
 295   }
 296
 297   @Override
 298   public String toString()
 299   {
 300     return id;
 301   }
 302
 303   /**
 304    * Getter provided for Castor binding only. Application code should call
 305    * getProperty() or getProperties() instead.
 306    *
 307    * @deprecated
 308    * @see #getProperty(String)
 309    * @see #getProperties()
 310    * @see jalview.ws.dbsources.Uniprot#getUniprotEntries
 311    * @return
 312    */
 313   @Deprecated
 314   public Hashtable<String, Object> getProps()
 315   {
 316     return properties;
 317   }
 318
 319   /**
 320    * Setter provided for Castor binding only. Application code should call
 321    * setProperty() instead.
 322    *
 323    * @deprecated
 324    * @return
 325    */
 326   @Deprecated
 327   public void setProps(Hashtable<String, Object> props)
 328   {
 329     properties = props;
 330   }
 331
 332   /**
 333    * Answers true if this object is either equivalent to, or can be 'improved'
 334    * by, the given entry.
 335    * <p>
 336    * If newEntry has the same id (ignoring case), and doesn't have a conflicting
 337    * file spec or chain code, then update this entry from its file and/or chain
 338    * code.
 339    *
 340    * @param newEntry
 341    * @return true if modifications were made
 342    */
 343   public boolean updateFrom(PDBEntry newEntry)
 344   {
 345     if (this.equals(newEntry))
 346     {
 347       return true;
 348     }
 349
 350     String newId = newEntry.getId();
 351     if (newId == null || getId() == null)
 352     {
 353       return false; // shouldn't happen
 354     }
 355
 356     /*
 357      * id has to match (ignoring case)
 358      */
 359     if (!getId().equalsIgnoreCase(newId))
 360     {
 361       return false;
 362     }
 363
 364     /*
 365      * Don't update if associated with different structure files
 366      */
 367     String newFile = newEntry.getFile();
 368     if (newFile != null && getFile() != null && !newFile.equals(getFile()))
 369     {
 370       return false;
 371     }
 372
 373     /*
 374      * Don't update if associated with different chains (ignoring case)
 375      */
 376     String newChain = newEntry.getChainCode();
 377     if (newChain != null && newChain.length() > 0 && getChainCode() != null
 378             && getChainCode().length() > 0
 379             && !getChainCode().equalsIgnoreCase(newChain))
 380     {
 381       return false;
 382     }
 383
 384     /*
 385      * set file path if not already set
 386      */
 387     String newType = newEntry.getType();
 388     if (getFile() == null && newFile != null)
 389     {
 390       setFile(newFile);
 391       setType(newType);
 392     }
 393
 394     /*
 395      * set file type if new entry has it and we don't
 396      * (for the case where file was not updated)
 397      */
 398     if (getType() == null && newType != null)
 399     {
 400       setType(newType);
 401     }
 402
 403     /*
 404      * set chain if not already set (we excluded differing
 405      * chains earlier) (ignoring case change only)
 406      */
 407     if (newChain != null && newChain.length() > 0
 408             && !newChain.equalsIgnoreCase(getChainCode()))
 409     {
 410       setChainCode(newChain);
 411     }
 412
 413     /*
 414      * copy any new or modified properties
 415      */
 416     Enumeration<String> newProps = newEntry.getProperties();
 417     while (newProps.hasMoreElements())
 418     {
 419       /*
 420        * copy properties unless value matches; this defends against changing
 421        * the case of chain_code which is wrapped in a CaseInsensitiveString
 422        */
 423       String key = newProps.nextElement();
 424       Object value = newEntry.getProperty(key);
 425       if (!value.equals(getProperty(key)))
 426       {
 427         setProperty(key, value);
 428       }
 429     }
 430     return true;
 431   }
 432 }