001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021package org.biojava.nbio.structure.align.util;
022
023import java.io.IOException;
024import java.util.ArrayList;
025import java.util.Collection;
026import java.util.Collections;
027import java.util.List;
028import java.util.TreeSet;
029
030import org.biojava.nbio.core.util.InputStreamProvider;
031import org.biojava.nbio.structure.*;
032import org.biojava.nbio.structure.align.client.StructureName;
033import org.biojava.nbio.structure.cath.CathDatabase;
034import org.biojava.nbio.structure.cath.CathDomain;
035import org.biojava.nbio.structure.cath.CathFactory;
036import org.biojava.nbio.structure.domain.PDPProvider;
037import org.biojava.nbio.structure.domain.RemotePDPProvider;
038import org.biojava.nbio.structure.io.FileParsingParameters;
039import org.biojava.nbio.structure.io.LocalPDBDirectory.FetchBehavior;
040import org.biojava.nbio.structure.io.LocalPDBDirectory.ObsoleteBehavior;
041import org.biojava.nbio.structure.io.MMCIFFileReader;
042import org.biojava.nbio.structure.io.MMTFFileReader;
043import org.biojava.nbio.structure.io.PDBFileReader;
044import org.biojava.nbio.core.util.FileDownloadUtils;
045import org.biojava.nbio.structure.quaternary.BiologicalAssemblyBuilder;
046import org.biojava.nbio.structure.quaternary.BiologicalAssemblyTransformation;
047import org.biojava.nbio.structure.scop.CachedRemoteScopInstallation;
048import org.biojava.nbio.structure.scop.ScopDatabase;
049import org.biojava.nbio.structure.scop.ScopDescription;
050import org.biojava.nbio.structure.scop.ScopDomain;
051import org.biojava.nbio.structure.scop.ScopFactory;
052import org.slf4j.Logger;
053import org.slf4j.LoggerFactory;
054
055/**
056 * A utility class that provides easy access to Structure objects. If you are running a script that is frequently
057 * re-using the same PDB structures, the AtomCache keeps an in-memory cache of the files for quicker access. The cache
058 * is a soft-cache, this means it won't cause out of memory exceptions, but garbage collects the data if the Java
059 * virtual machine needs to free up space. The AtomCache is thread-safe.
060 *
061 * @author Andreas Prlic
062 * @author Spencer Bliven
063 * @author Peter Rose
064 * @since 3.0
065 */
066public class AtomCache {
067
068        private static final Logger logger = LoggerFactory.getLogger(AtomCache.class);
069
070        /**
071         * The default output bioassembly style: if true the bioassemblies are multimodel,
072         * if false the bioassemblies are flat with renamed chains for symmetry-partners.
073         */
074        public static final boolean DEFAULT_BIOASSEMBLY_STYLE = false;
075
076        public static final String BIOL_ASSEMBLY_IDENTIFIER = "BIO:";
077        public static final String CHAIN_NR_SYMBOL = ":";
078        public static final String CHAIN_SPLIT_SYMBOL = ".";
079
080        public static final String PDP_DOMAIN_IDENTIFIER = "PDP:";
081
082        public static final String UNDERSCORE = "_";
083
084        private static final String FILE_SEPARATOR = System.getProperty("file.separator");
085
086        protected FileParsingParameters params;
087        protected PDPProvider pdpprovider;
088
089        private FetchBehavior fetchBehavior;
090        private ObsoleteBehavior obsoleteBehavior;
091
092        private String cachePath;
093
094        // make sure IDs are loaded uniquely
095        private Collection<String> currentlyLoading = Collections.synchronizedCollection(new TreeSet<String>());
096
097        private String path;
098
099        private boolean useMmCif;
100        private boolean useMmtf;
101
102        /**
103         * Default AtomCache constructor.
104         *
105         * Usually stores files in a temp directory, but this can be overriden by setting the PDB_DIR variable at runtime.
106         *
107         * @see UserConfiguration#UserConfiguration()
108         */
109        public AtomCache() {
110                this(new UserConfiguration());
111        }
112
113        /**
114         * Creates an instance of an AtomCache that is pointed to the a particular path in the file system. It will use the same value for pdbFilePath and cachePath.
115         *
116         * @param pdbFilePath
117         *            a directory in the file system to use as a location to cache files.
118         */
119        public AtomCache(String pdbFilePath) {
120                this(pdbFilePath,pdbFilePath);
121        }
122
123        /**
124         * Creates an instance of an AtomCache that is pointed to the a particular path in the file system.
125         *
126         * @param pdbFilePath
127         *            a directory in the file system to use as a location to cache files.
128         * @param cachePath
129         */
130        public AtomCache(String pdbFilePath, String cachePath) {
131
132                logger.debug("Initialising AtomCache with pdbFilePath={}, cachePath={}",pdbFilePath, cachePath);
133
134                if (!pdbFilePath.endsWith(FILE_SEPARATOR)) {
135                        pdbFilePath += FILE_SEPARATOR;
136                }
137
138                // we are caching the binary files that contain the PDBs gzipped
139                // that is the most memory efficient way of caching...
140                // set the input stream provider to caching mode
141                System.setProperty(InputStreamProvider.CACHE_PROPERTY, "true");
142
143                setPath(pdbFilePath);
144
145                this.cachePath = cachePath;
146
147                fetchBehavior = FetchBehavior.DEFAULT;
148                obsoleteBehavior = ObsoleteBehavior.DEFAULT;
149
150                currentlyLoading.clear();
151                params = new FileParsingParameters();
152
153                setUseMmCif(false);
154                setUseMmtf(true);
155
156        }
157
158        /**
159         * Creates a new AtomCache object based on the provided UserConfiguration.
160         *
161         * @param config
162         *            the UserConfiguration to use for this cache.
163         */
164        public AtomCache(UserConfiguration config) {
165                this(config.getPdbFilePath(), config.getCacheFilePath());
166                fetchBehavior = config.getFetchBehavior();
167                obsoleteBehavior = config.getObsoleteBehavior();
168                useMmCif = config.getFileFormat().equals( UserConfiguration.MMCIF_FORMAT );
169
170                if ( useMmCif)
171                        useMmtf = false;
172
173        }
174
175        /**
176         * Returns the CA atoms for the provided name. See {@link #getStructure(String)} for supported naming conventions.
177         * <p>
178         * This method only works with protein chains. Use {@link #getRepresentativeAtoms(String)}
179         * for a more general solution.
180         * @param name
181         * @return an array of Atoms.
182         * @throws IOException
183         * @throws StructureException
184         * @see
185         */
186        public Atom[] getAtoms(String name) throws IOException, StructureException {
187                return getAtoms(new StructureName(name));
188        }
189        public Atom[] getAtoms(StructureIdentifier name) throws IOException, StructureException {
190
191                Atom[] atoms = null;
192
193                // System.out.println("loading " + name);
194                Structure s = getStructure(name);
195
196                atoms = StructureTools.getAtomCAArray(s);
197
198                /*
199                 * synchronized (cache){ cache.put(name, atoms); }
200                 */
201
202                return atoms;
203        }
204        /**
205         * Returns the representative atoms for the provided name.
206         * See {@link #getStructure(String)} for supported naming conventions.
207         *
208         * @param name
209         * @return an array of Atoms.
210         * @throws IOException
211         * @throws StructureException
212         * @see
213         */
214        public Atom[] getRepresentativeAtoms(String name) throws IOException, StructureException {
215                return getRepresentativeAtoms(new StructureName(name));
216        }
217
218        public Atom[] getRepresentativeAtoms(StructureIdentifier name) throws IOException, StructureException {
219
220                Atom[] atoms = null;
221
222                Structure s = getStructure(name);
223
224                atoms = StructureTools.getRepresentativeAtomArray(s);
225
226                /*
227                 * synchronized (cache){ cache.put(name, atoms); }
228                 */
229
230                return atoms;
231        }
232
233        /**
234         * Returns the biological assembly for a given PDB ID and bioAssemblyId, by building the
235         * assembly from the biounit annotations found in {@link Structure#getPDBHeader()}
236         * <p>
237         * Note, the number of available biological unit files
238         * varies. Many entries don't have a biological assembly specified (e.g. NMR structures), many entries have only one
239         * biological assembly (bioAssemblyId=1), and some structures have multiple biological assemblies.
240         *
241         * @param pdbId
242         *            the PDB ID
243         * @param bioAssemblyId
244         *            the 1-based index of the biological assembly (0 gets the asymmetric unit)
245         * @param multiModel if true the output Structure will be a multi-model one with one transformId per model,
246         * if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId).
247         * @return a structure object
248         * @throws IOException
249         * @throws StructureException if biassemblyId < 0 or other problems while loading structure
250         * @author Peter Rose
251         * @since 3.2
252         */
253        public Structure getBiologicalAssembly(String pdbId, int bioAssemblyId, boolean multiModel)
254                        throws StructureException, IOException {
255
256                if (bioAssemblyId < 0) {
257                        throw new StructureException("bioAssemblyID must be nonnegative: " + pdbId + " bioAssemblyId "
258                                        + bioAssemblyId);
259                }
260
261                boolean prevIsParseBioAssembly = getFileParsingParams().isParseBioAssembly();
262
263                if (!getFileParsingParams().isParseBioAssembly()) {
264                        getFileParsingParams().setParseBioAssembly(true);
265                }
266
267                Structure asymUnit = getStructureForPdbId(pdbId);
268
269                getFileParsingParams().setParseBioAssembly(prevIsParseBioAssembly);
270
271                if (asymUnit.getPDBHeader() == null || asymUnit.getPDBHeader().getBioAssemblies()==null) {
272                        logger.info("No bioassembly information found for {}, returning asymmetric unit as biological assembly", pdbId);
273                        return asymUnit;
274                }
275
276                // 0 ... asym unit
277                if ( bioAssemblyId == 0) {
278                        logger.info("Requested biological assembly 0 for PDB id "+pdbId+", returning asymmetric unit");
279                        return asymUnit;
280                }
281                // does it exist?
282                if (!asymUnit.getPDBHeader().getBioAssemblies().containsKey(bioAssemblyId)) {
283                        throw new StructureException("No biological assembly available for biological assembly id " + bioAssemblyId + " of " + pdbId);
284                }
285
286                List<BiologicalAssemblyTransformation> transformations =
287                                asymUnit.getPDBHeader().getBioAssemblies().get(bioAssemblyId).getTransforms();
288
289
290                if ( transformations == null || transformations.size() == 0){
291
292                        throw new StructureException("Could not load transformations to recreate biological assembly id " + bioAssemblyId + " of " + pdbId);
293
294                }
295
296                BiologicalAssemblyBuilder builder = new BiologicalAssemblyBuilder();
297
298                // if we use mmcif or mmtf, then we need to pass useAsymIds=true
299                boolean useAsymIds = false;
300                if (useMmCif) useAsymIds = true;
301                if (useMmtf) useAsymIds = true;
302                return builder.rebuildQuaternaryStructure(asymUnit, transformations, useAsymIds, multiModel);
303
304        }
305
306        /**
307         * Returns the default biological unit (bioassemblyId=1, known in PDB as pdb1.gz). If it is not available,
308         * the asymmetric unit will be returned, e.g. for NMR structures.
309         *
310         * <p>Biological assemblies can also be accessed using
311         * <tt>getStructure("BIO:<i>[pdbId]</i>")</tt>
312         * @param pdbId the PDB id
313         * @param multiModel if true the output Structure will be a multi-model one with one transformId per model,
314         * if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId).
315         * @return a structure object
316         * @throws IOException
317         * @throws StructureException
318         * @since 4.2
319         */
320        public Structure getBiologicalAssembly(String pdbId, boolean multiModel) throws StructureException, IOException {
321
322                boolean prevIsParseBioAssembly = getFileParsingParams().isParseBioAssembly();
323
324                if (!getFileParsingParams().isParseBioAssembly()) {
325                        getFileParsingParams().setParseBioAssembly(true);
326                }
327
328                Structure asymUnit = getStructureForPdbId(pdbId);
329
330                getFileParsingParams().setParseBioAssembly(prevIsParseBioAssembly);
331
332
333                if (asymUnit.getPDBHeader() == null || asymUnit.getPDBHeader().getBioAssemblies()==null) {
334                        logger.info("No bioassembly information found for {}, returning asymmetric unit as biological assembly", pdbId);
335                        return asymUnit;
336                }
337
338                int bioAssemblyId = 1;
339
340                // does it exist?
341                if (!asymUnit.getPDBHeader().getBioAssemblies().containsKey(bioAssemblyId)) {
342                        return asymUnit;
343                }
344
345                List<BiologicalAssemblyTransformation> transformations =
346                                asymUnit.getPDBHeader().getBioAssemblies().get(bioAssemblyId).getTransforms();
347
348
349                if ( transformations == null || transformations.size() == 0){
350
351                        throw new StructureException("Could not load transformations to recreate biological assembly id " + bioAssemblyId + " of " + pdbId);
352
353                }
354
355                BiologicalAssemblyBuilder builder = new BiologicalAssemblyBuilder();
356
357                // if we use mmcif or mmtf, then we need to pass useAsymIds=true
358                boolean useAsymIds = false;
359                if (useMmCif) useAsymIds = true;
360                if (useMmtf) useAsymIds = true;
361                return builder.rebuildQuaternaryStructure(asymUnit, transformations, useAsymIds, multiModel);
362
363        }
364
365        /**
366         * Returns all biological assemblies for given PDB id.
367         * @param pdbId
368         * @param multiModel if true the output Structure will be a multi-model one with one transformId per model,
369         * if false the outputStructure will be as the original with added chains with renamed asymIds (in the form originalAsymId_transformId and originalAuthId_transformId).
370         * @return
371         * @throws StructureException
372         * @throws IOException
373         * @since 5.0
374         */
375        public List<Structure> getBiologicalAssemblies(String pdbId, boolean multiModel) throws StructureException, IOException {
376
377                List<Structure> assemblies = new ArrayList<>();
378
379                boolean prevIsParseBioAssembly = getFileParsingParams().isParseBioAssembly();
380
381                if (!getFileParsingParams().isParseBioAssembly()) {
382                        getFileParsingParams().setParseBioAssembly(true);
383                }
384
385                Structure asymUnit = getStructureForPdbId(pdbId);
386
387                getFileParsingParams().setParseBioAssembly(prevIsParseBioAssembly);
388
389
390                if (asymUnit.getPDBHeader() == null || asymUnit.getPDBHeader().getBioAssemblies()==null) {
391                        logger.info("No bioassembly information found for {}, returning asymmetric unit as the only biological assembly", pdbId);
392                        assemblies.add(asymUnit);
393                        return assemblies;
394                }
395
396
397                for (int bioAssemblyId : asymUnit.getPDBHeader().getBioAssemblies().keySet()) {
398                        List<BiologicalAssemblyTransformation> transformations =
399                                        asymUnit.getPDBHeader().getBioAssemblies().get(bioAssemblyId).getTransforms();
400
401
402                        if ( transformations == null || transformations.size() == 0){
403
404                                logger.info("Could not load transformations to recreate biological assembly id " + bioAssemblyId + " of " + pdbId+". Assembly id will be missing in biological assemblies.");
405                                continue;
406                        }
407
408                        BiologicalAssemblyBuilder builder = new BiologicalAssemblyBuilder();
409
410                        // if we use mmcif or mmtf, then we need to pass useAsymIds=true
411                        boolean useAsymIds = false;
412                        if (useMmCif) useAsymIds = true;
413                        if (useMmtf) useAsymIds = true;
414                        Structure s = builder.rebuildQuaternaryStructure(asymUnit, transformations, useAsymIds, multiModel);
415                        assemblies.add(s);
416                }
417                return assemblies;
418        }
419
420        /**
421         * Returns the path that contains the caching file for utility data, such as domain definitions.
422         *
423         * @return
424         */
425        public String getCachePath() {
426                return cachePath;
427        }
428
429        public FileParsingParameters getFileParsingParams() {
430                return params;
431        }
432
433        /**
434         * Get the path that is used to cache PDB files.
435         *
436         * @return path to a directory
437         */
438        public String getPath() {
439                return path;
440        }
441
442        public PDPProvider getPdpprovider() {
443                return pdpprovider;
444        }
445
446        /**
447         * Request a Structure based on a <i>name</i>.
448         *
449         * <pre>
450         *              Formal specification for how to specify the <i>name</i>:
451         *
452         *              name     := pdbID
453         *                             | pdbID '.' chainID
454         *                             | pdbID '.' range
455         *                             | scopID
456         *              range         := '('? range (',' range)? ')'?
457         *                             | chainID
458         *                             | chainID '_' resNum '-' resNum
459         *              pdbID         := [0-9][a-zA-Z0-9]{3}
460         *              chainID       := [a-zA-Z0-9]
461         *              scopID        := 'd' pdbID [a-z_][0-9_]
462         *              resNum        := [-+]?[0-9]+[A-Za-z]?
463         *
464         *
465         *              Example structures:
466         *              1TIM     #whole structure
467         *              4HHB.C     #single chain
468         *              4GCR.A_1-83     #one domain, by residue number
469         *              3AA0.A,B     #two chains treated as one structure
470         *              d2bq6a1     #scop domain
471         * </pre>
472         *
473         * With the additional set of rules:
474         *
475         * <ul>
476         * <li>If only a PDB code is provided, the whole structure will be return including ligands, but the first model
477         * only (for NMR).
478         * <li>Chain IDs are case sensitive, PDB ids are not. To specify a particular chain write as: 4hhb.A or 4HHB.A</li>
479         * <li>To specify a SCOP domain write a scopId e.g. d2bq6a1. Some flexibility can be allowed in SCOP domain names,
480         * see {@link #setStrictSCOP(boolean)}</li>
481         * <li>URLs are accepted as well</li>
482         * </ul>
483         *
484         * <p>Note that this method should not be used in StructureIdentifier
485         * implementations to avoid circular calls.
486         * @param name
487         * @return a Structure object, or null if name appears improperly formated (eg too short, etc)
488         * @throws IOException
489         *             The PDB file cannot be cached due to IO errors
490         * @throws StructureException
491         *             The name appeared valid but did not correspond to a structure. Also thrown by some submethods upon
492         *             errors, eg for poorly formatted subranges.
493         */
494        public Structure getStructure(String name) throws IOException, StructureException {
495                StructureName structureName = new StructureName(name);
496
497                return getStructure(structureName);
498        }
499
500        /**
501         * Get the structure corresponding to the given {@link StructureIdentifier}.
502         * Equivalent to calling {@link StructureIdentifier#loadStructure(AtomCache)}
503         * followed by {@link StructureIdentifier#reduce(Structure)}.
504         *
505         * <p>Note that this method should not be used in StructureIdentifier
506         * implementations to avoid circular calls.
507         * @param strucId
508         * @return
509         * @throws IOException
510         * @throws StructureException
511         */
512        public Structure getStructure(StructureIdentifier strucId) throws IOException, StructureException {
513                Structure s = strucId.loadStructure(this);
514                Structure r = strucId.reduce(s);
515                r.setStructureIdentifier(strucId);
516                return r;
517        }
518
519        /**
520         * Returns the representation of a {@link ScopDomain} as a BioJava {@link Structure} object.
521         *
522         * @param domain
523         *            a SCOP domain
524         * @return a Structure object
525         * @throws IOException
526         * @throws StructureException
527         */
528        public Structure getStructureForDomain(ScopDomain domain) throws IOException, StructureException {
529                return getStructureForDomain(domain, ScopFactory.getSCOP());
530        }
531
532        /**
533         * Returns the representation of a {@link ScopDomain} as a BioJava {@link Structure} object.
534         *
535         * @param domain
536         *            a SCOP domain
537         * @param scopDatabase
538         *            A {@link ScopDatabase} to use
539         * @return a Structure object
540         * @throws IOException
541         * @throws StructureException
542         */
543        public Structure getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase) throws IOException,
544                        StructureException {
545                return getStructureForDomain(domain, scopDatabase, false);
546        }
547
548        /**
549         * Returns the representation of a {@link ScopDomain} as a BioJava {@link Structure} object.
550         *
551         * @param domain
552         *            a SCOP domain
553         * @param scopDatabase
554         *            A {@link ScopDatabase} to use
555         * @param strictLigandHandling
556         *            If set to false, hetero-atoms are included if and only if they belong to a chain to which the SCOP
557         *            domain belongs; if set to true, hetero-atoms are included if and only if they are strictly within the
558         *            definition (residue numbers) of the SCOP domain
559         * @return a Structure object
560         * @throws IOException
561         * @throws StructureException
562         */
563        public Structure getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase, boolean strictLigandHandling)
564                        throws IOException, StructureException {
565
566                String pdbId = domain.getPdbId();
567                Structure fullStructure = getStructureForPdbId(pdbId);
568                Structure structure = domain.reduce(fullStructure);
569
570                // TODO It would be better to move all of this into the reduce method,
571                // but that would require ligand handling properties in StructureIdentifiers
572
573                // because ligands sometimes occur after TER records in PDB files, we may need to add some ligands back in
574                // specifically, we add a ligand if and only if it occurs within the domain
575                AtomPositionMap map = null;
576                List<ResidueRangeAndLength> rrs = null;
577                if (strictLigandHandling) {
578                        map = new AtomPositionMap(StructureTools.getAllAtomArray(fullStructure), AtomPositionMap.ANYTHING_MATCHER);
579                        rrs = ResidueRangeAndLength.parseMultiple(domain.getRanges(), map);
580                }
581                for (Chain chain : fullStructure.getNonPolyChains()) {
582
583                        if (!structure.hasPdbChain(chain.getName())) {
584                                continue; // we can't do anything with a chain our domain
585                        }
586
587                        Chain newChain;
588                        if (! structure.hasNonPolyChain(chain.getId())) {
589                                newChain = new ChainImpl();
590                                newChain.setId(chain.getId());
591                                newChain.setName(chain.getName());
592                                newChain.setEntityInfo(chain.getEntityInfo());
593                                structure.addChain(newChain);
594                        } else {
595                                newChain = structure.getNonPolyChain(chain.getId());
596                        }
597                        List<Group> ligands = StructureTools.filterLigands(chain.getAtomGroups());
598                        for (Group group : ligands) {
599                                boolean shouldContain = true;
600                                if (strictLigandHandling) {
601                                        shouldContain = false; // whether the ligand occurs within the domain
602                                        for (ResidueRange rr : rrs) {
603                                                if (rr.contains(group.getResidueNumber(), map)) {
604                                                        shouldContain = true;
605                                                }
606                                        }
607                                }
608                                boolean alreadyContains = newChain.getAtomGroups().contains(group); // we don't want to add duplicate
609                                                                                                                                                                        // ligands
610                                if (shouldContain && !alreadyContains) {
611
612                                        newChain.addGroup(group);
613
614                                }
615                        }
616                }
617
618                // build a more meaningful description for the new structure
619                StringBuilder header = new StringBuilder();
620                header.append(domain.getClassificationId());
621                if (scopDatabase != null) {
622                        int sf = domain.getSuperfamilyId();
623                        ScopDescription description = scopDatabase.getScopDescriptionBySunid(sf);
624                        if (description != null) {
625                                header.append(" | ");
626                                header.append(description.getDescription());
627                        }
628                }
629                structure.getPDBHeader().setDescription(header.toString());
630
631                return structure;
632
633        }
634
635        /**
636         * Returns the representation of a {@link ScopDomain} as a BioJava {@link Structure} object.
637         *
638         * @param scopId
639         *            a SCOP Id
640         * @return a Structure object
641         * @throws IOException
642         * @throws StructureException
643         */
644        public Structure getStructureForDomain(String scopId) throws IOException, StructureException {
645                return getStructureForDomain(scopId, ScopFactory.getSCOP());
646        }
647
648        /**
649         * Returns the representation of a {@link ScopDomain} as a BioJava {@link Structure} object.
650         *
651         * @param scopId
652         *            a SCOP Id
653         * @param scopDatabase
654         *            A {@link ScopDatabase} to use
655         * @return a Structure object
656         * @throws IOException
657         * @throws StructureException
658         */
659        public Structure getStructureForDomain(String scopId, ScopDatabase scopDatabase) throws IOException,
660                        StructureException {
661                ScopDomain domain = scopDatabase.getDomainByScopID(scopId);
662                return getStructureForDomain(domain, scopDatabase);
663        }
664
665        /**
666         * Send a signal to the cache that the system is shutting down. Notifies underlying SerializableCache instances to
667         * flush themselves...
668         */
669        public void notifyShutdown() {
670                // System.out.println(" AtomCache got notify shutdown..");
671                if (pdpprovider != null) {
672                        if (pdpprovider instanceof RemotePDPProvider) {
673                                RemotePDPProvider remotePDP = (RemotePDPProvider) pdpprovider;
674                                remotePDP.flushCache();
675                        }
676                }
677
678                // todo: use a SCOP implementation that is backed by SerializableCache
679                ScopDatabase scopInstallation = ScopFactory.getSCOP();
680                if (scopInstallation != null) {
681                        if (scopInstallation instanceof CachedRemoteScopInstallation) {
682                                CachedRemoteScopInstallation cacheScop = (CachedRemoteScopInstallation) scopInstallation;
683                                cacheScop.flushCache();
684                        }
685                }
686
687        }
688
689        /**
690         * set the location at which utility data should be cached.
691         *
692         * @param cachePath
693         */
694        public void setCachePath(String cachePath) {
695                this.cachePath = cachePath;
696        }
697
698        public void setFileParsingParams(FileParsingParameters params) {
699                this.params = params;
700        }
701
702
703        /**
704         * <b>[Optional]</b> This method changes the behavior when obsolete entries
705         * are requested. Current behaviors are:
706         * <ul>
707         * <li>{@link ObsoleteBehavior#THROW_EXCEPTION THROW_EXCEPTION}
708         *   Throw a {@link StructureException} (the default)
709         * <li>{@link ObsoleteBehavior#FETCH_OBSOLETE FETCH_OBSOLETE}
710         *   Load the requested ID from the PDB's obsolete repository
711         * <li>{@link ObsoleteBehavior#FETCH_CURRENT FETCH_CURRENT}
712         *   Load the most recent version of the requested structure
713         *
714         * <p>This setting may be silently ignored by implementations which do not have
715         * access to the server to determine whether an entry is obsolete, such as
716         * if {@link #isAutoFetch()} is false. Note that an obsolete entry may still be
717         * returned even this is FETCH_CURRENT if the entry is found locally.
718         *
719         * @param fetchFileEvenIfObsolete Whether to fetch obsolete records
720         * @see #setFetchCurrent(boolean)
721         * @since 4.0.0
722         */
723        public void setObsoleteBehavior(ObsoleteBehavior behavior) {
724                obsoleteBehavior = behavior;
725        }
726
727        /**
728         * Returns how this instance deals with obsolete entries. Note that this
729         * setting may be ignored by some implementations or in some situations,
730         * such as when {@link #isAutoFetch()} is false.
731         *
732         * <p>For most implementations, the default value is
733         * {@link ObsoleteBehavior#THROW_EXCEPTION THROW_EXCEPTION}.
734         *
735         * @return The ObsoleteBehavior
736         * @since 4.0.0
737         */
738        public ObsoleteBehavior getObsoleteBehavior() {
739                return obsoleteBehavior;
740        }
741
742        /**
743         * Get the behavior for fetching files from the server
744         * @return
745         */
746        public FetchBehavior getFetchBehavior() {
747                return fetchBehavior;
748        }
749        /**
750         * Set the behavior for fetching files from the server
751         * @param fetchBehavior
752         */
753        public void setFetchBehavior(FetchBehavior fetchBehavior) {
754                this.fetchBehavior = fetchBehavior;
755        }
756
757        /**
758         * Set the path that is used to cache PDB files.
759         *
760         * @param path
761         *            to a directory
762         */
763        public void setPath(String path) {
764                this.path = FileDownloadUtils.expandUserHome(path);
765        }
766
767        public void setPdpprovider(PDPProvider pdpprovider) {
768                this.pdpprovider = pdpprovider;
769        }
770
771        /**
772         * @return the useMmCif
773         */
774        public boolean isUseMmCif() {
775                return useMmCif;
776        }
777
778        /**
779         * @param useMmCif
780         *            the useMmCif to set
781         */
782        public void setUseMmCif(boolean useMmCif) {
783                this.useMmCif = useMmCif;
784                // Either way the user wants to use PDB or MMCIF
785                this.useMmtf = false;
786        }
787
788        /**
789         * Set whether to use mmtf.
790         * @param useMmtf the input boolean to set
791         */
792        public void setUseMmtf(boolean useMmtf) {
793                this.useMmtf = useMmtf;
794                if(useMmtf){
795                        useMmCif=false;
796                }
797
798        }
799
800        /** Returns useMmtf flag
801         *
802         * @return true if will load data via mmtf file format
803         */
804        public boolean isUseMmtf(){
805                return this.useMmtf;
806        }
807
808        private boolean checkLoading(String name) {
809                return currentlyLoading.contains(name);
810
811        }
812
813        /**
814         * Returns a {@link Structure} corresponding to the CATH identifier supplied in {@code structureName}, using the the {@link CathDatabase}
815         * at {@link CathFactory#getCathDatabase()}.
816         */
817        public Structure getStructureForCathDomain(StructureName structureName) throws IOException, StructureException {
818                return getStructureForCathDomain(structureName, CathFactory.getCathDatabase());
819        }
820
821        /**
822         * Returns a {@link Structure} corresponding to the CATH identifier supplied in {@code structureName}, using the specified {@link CathDatabase}.
823         */
824        public Structure getStructureForCathDomain(StructureName structureName, CathDatabase cathInstall) throws IOException, StructureException {
825
826                CathDomain cathDomain = cathInstall.getDomainByCathId(structureName.getIdentifier());
827
828                Structure s = getStructureForPdbId(cathDomain.getIdentifier());
829                Structure n = cathDomain.reduce(s);
830
831                // add the ligands of the chain...
832
833                Chain newChain = n.getPolyChainByPDB(structureName.getChainId());
834                List<Chain> origChains = s.getNonPolyChainsByPDB(structureName.getChainId());
835                for ( Chain origChain : origChains) {
836                        List<Group> ligands = origChain.getAtomGroups();
837
838                        for (Group g : ligands) {
839                                if (!newChain.getAtomGroups().contains(g)) {
840                                        newChain.addGroup(g);
841                                }
842                        }
843                }
844
845                return n;
846        }
847
848        protected void flagLoading(String name) {
849                if (!currentlyLoading.contains(name)) {
850
851                        currentlyLoading.add(name);
852                }
853        }
854
855        protected void flagLoadingFinished(String name) {
856
857                currentlyLoading.remove(name);
858        }
859
860        /**
861         * Loads a structure directly by PDB ID
862         * @param pdbId
863         * @return
864         * @throws IOException
865         * @throws StructureException
866         */
867        public Structure getStructureForPdbId(String pdbId) throws IOException, StructureException {
868                if(pdbId == null)
869                        return null;
870                if(pdbId.length() != 4) {
871                        throw new StructureException("Unrecognized PDB ID: "+pdbId);
872                }
873                while (checkLoading(pdbId)) {
874                        // waiting for loading to be finished...
875
876                        try {
877                                Thread.sleep(100);
878                        } catch (InterruptedException e) {
879                                logger.error(e.getMessage());
880                        }
881
882                }
883
884                Structure s;
885                if (useMmtf) {
886                        logger.debug("loading from mmtf");
887                        s = loadStructureFromMmtfByPdbId(pdbId);
888                }
889                else if (useMmCif) {
890                        logger.debug("loading from mmcif");
891                        s = loadStructureFromCifByPdbId(pdbId);
892                } else {
893                        logger.debug("loading from pdb");
894                        s = loadStructureFromPdbByPdbId(pdbId);
895                }
896                return s;
897        }
898
899        /**
900         * Load a {@link Structure} from MMTF either from the local file system.
901         * @param pdbId the input PDB id
902         * @return the {@link Structure} object of the parsed structure
903         * @throws IOException error reading from Web or file system
904         */
905        private Structure loadStructureFromMmtfByPdbId(String pdbId) throws IOException {
906                logger.debug("Loading structure {} from mmtf file.", pdbId);
907                MMTFFileReader reader = new MMTFFileReader();
908                reader.setFetchBehavior(fetchBehavior);
909                reader.setObsoleteBehavior(obsoleteBehavior);
910                Structure structure = reader.getStructureById(pdbId.toLowerCase());
911                return structure;
912        }
913
914        protected Structure loadStructureFromCifByPdbId(String pdbId) throws IOException, StructureException {
915
916                logger.debug("Loading structure {} from mmCIF file {}.", pdbId, path);
917                Structure s;
918                flagLoading(pdbId);
919                try {
920                        MMCIFFileReader reader = new MMCIFFileReader(path);
921                        reader.setFetchBehavior(fetchBehavior);
922                        reader.setObsoleteBehavior(obsoleteBehavior);
923                        reader.setFileParsingParameters(params);
924                        s = reader.getStructureById(pdbId.toLowerCase());
925
926                } finally {
927                        flagLoadingFinished(pdbId);
928                }
929
930                return s;
931        }
932
933        protected Structure loadStructureFromPdbByPdbId(String pdbId) throws IOException, StructureException {
934
935                logger.debug("Loading structure {} from PDB file {}.", pdbId, path);
936                Structure s;
937                flagLoading(pdbId);
938                try {
939                        PDBFileReader reader = new PDBFileReader(path);
940                        reader.setFetchBehavior(fetchBehavior);
941                        reader.setObsoleteBehavior(obsoleteBehavior);
942
943                        reader.setFileParsingParameters(params);
944
945                        s = reader.getStructureById(pdbId.toLowerCase());
946
947                } finally {
948                        flagLoadingFinished(pdbId);
949                }
950
951                return s;
952        }
953
954}