AtomCache

java.lang.Object
- org.biojava.bio.structure.align.util.AtomCache

```
public class AtomCache
extends java.lang.Object
```
A utility class that provides easy access to Structure objects. If you are running a script that is frequently re-using the same PDB structures, the AtomCache keeps an in-memory cache of the files for quicker access. The cache is a soft-cache, this means it won't cause out of memory exceptions, but garbage collects the data if the Java virtual machine needs to free up space. The AtomCache is thread-safe.

Since:

3.0

Author:

Andreas Prlic, Spencer Bliven, Peter Rose

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`BIOL_ASSEMBLY_IDENTIFIER`
`static java.lang.String`	`CHAIN_NR_SYMBOL`
`static java.lang.String`	`CHAIN_SPLIT_SYMBOL`
`protected FileParsingParameters`	`params`
`static java.lang.String`	`PDP_DOMAIN_IDENTIFIER`
`protected PDPProvider`	`pdpprovider`
`static java.util.regex.Pattern`	`scopIDregex`
`static java.lang.String`	`UNDERSCORE`

Constructor Summary

Constructors
Constructor and Description
`AtomCache()` Default AtomCache constructor.
`AtomCache(java.lang.String pdbFilePath, boolean isSplit)` Creates an instance of an AtomCache that is pointed to the a particular path in the file system.
`AtomCache(UserConfiguration config)` Creates a new AtomCache object based on the provided UserConfiguration.

Method Summary

Methods
Modifier and Type	Method and Description
`protected void`	`flagLoading(java.lang.String name)`
`protected void`	`flagLoadingFinished(java.lang.String name)`
`Atom[]`	`getAtoms(java.lang.String name)` Returns the CA atoms for the provided name.
`Atom[]`	`getAtoms(java.lang.String name, boolean clone)` Deprecated. does the same as `getAtoms(String)` ;
`Structure`	`getBiologicalAssembly(java.lang.String pdbId, int bioAssemblyId, boolean bioAssemblyFallback)` Loads the biological assembly for a given PDB ID and bioAssemblyId.
`Structure`	`getBiologicalUnit(java.lang.String pdbId)` Loads the default biological unit (*.pdb1.gz) file.
`java.lang.String`	`getCachePath()` Returns the path that contains the caching file for utility data, such as domain definitons.
`FileParsingParameters`	`getFileParsingParams()`
`java.lang.String`	`getPath()` Get the path that is used to cache PDB files.
`PDPProvider`	`getPdpprovider()`
`Structure`	`getStructure(java.lang.String name)` Request a Structure based on a name.
`Structure`	`getStructureForCathDomain(StructureName structureName)` Returns a `Structure` corresponding to the CATH identifier supplied in `structureName`, using the the `CathDatabase` at `CathFactory.getCathDatabase()`.
`Structure`	`getStructureForCathDomain(StructureName structureName, CathDatabase cathInstall)` Returns a `Structure` corresponding to the CATH identifier supplied in `structureName`, using the specified `CathDatabase`.
`Structure`	`getStructureForDomain(ScopDomain domain)` Returns the representation of a `ScopDomain` as a BioJava `Structure` object.
`Structure`	`getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase)` Returns the representation of a `ScopDomain` as a BioJava `Structure` object.
`Structure`	`getStructureForDomain(ScopDomain domain, ScopDatabase scopDatabase, boolean strictLigandHandling)` Returns the representation of a `ScopDomain` as a BioJava `Structure` object.
`Structure`	`getStructureForDomain(java.lang.String scopId)` Returns the representation of a `ScopDomain` as a BioJava `Structure` object.
`Structure`	`getStructureForDomain(java.lang.String scopId, ScopDatabase scopDatabase)` Returns the representation of a `ScopDomain` as a BioJava `Structure` object.
`boolean`	`isAutoFetch()` Does the cache automatically download files that are missing from the local installation from the PDB FTP site?
`boolean`	`isFetchCurrent()` N.B. This feature won't work unless the structure wasn't found & autoFetch is set to `true`.
`boolean`	`isFetchFileEvenIfObsolete()` forces the cache to fetch the file if its status is OBSOLETE.
`boolean`	`isSplit()` Is the organization of files within the directory split, as on the PDB FTP servers, or are all files contained in one directory.
`boolean`	`isStrictSCOP()` Reports whether strict scop naming will be enforced, or whether this AtomCache should try to guess some simple variants on scop domains.
`boolean`	`isUseMmCif()`
`protected Structure`	`loadStructureFromCifByPdbId(java.lang.String pdbId)`
`protected Structure`	`loadStructureFromPdbByPdbId(java.lang.String pdbId)`
`void`	`notifyShutdown()` Send a signal to the cache that the system is shutting down.
`void`	`setAutoFetch(boolean autoFetch)` Does the cache automatically download files that are missing from the local installation from the PDB FTP site?
`void`	`setCachePath(java.lang.String cachePath)` set the location at which utility data should be cached.
`void`	`setFetchCurrent(boolean fetchNewestCurrent)` if enabled, the reader searches for the newest possible PDB ID, if not present in he local installation.
`void`	`setFetchFileEvenIfObsolete(boolean fetchFileEvenIfObsolete)` N.B. This feature won't work unless the structure wasn't found & autoFetch is set to `true`.
`void`	`setFileParsingParams(FileParsingParameters params)`
`void`	`setPath(java.lang.String path)` Set the path that is used to cache PDB files.
`void`	`setPdpprovider(PDPProvider pdpprovider)`
`void`	`setSplit(boolean isSplit)` Is the organization of files within the directory split, as on the PDB FTP servers, or are all files contained in one directory.
`void`	`setStrictSCOP(boolean strictSCOP)` When strictSCOP is enabled, SCOP domain identifiers (eg 'd1gbga_') are matched literally to the SCOP database.
`void`	`setUseMmCif(boolean useMmCif)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - BIOL_ASSEMBLY_IDENTIFIER
```
public static final java.lang.String BIOL_ASSEMBLY_IDENTIFIER
```
    See Also:
    Constant Field Values
  - CHAIN_NR_SYMBOL
```
public static final java.lang.String CHAIN_NR_SYMBOL
```
    See Also:
    Constant Field Values
  - CHAIN_SPLIT_SYMBOL
```
public static final java.lang.String CHAIN_SPLIT_SYMBOL
```
    See Also:
    Constant Field Values
  - PDP_DOMAIN_IDENTIFIER
```
public static final java.lang.String PDP_DOMAIN_IDENTIFIER
```
    See Also:
    Constant Field Values
  - scopIDregex
```
public static final java.util.regex.Pattern scopIDregex
```
  - UNDERSCORE
```
public static final java.lang.String UNDERSCORE
```
    See Also:
    Constant Field Values
  - params
```
protected FileParsingParameters params
```
  - pdpprovider
```
protected PDPProvider pdpprovider
```
- Constructor Detail
  - AtomCache
```
public AtomCache()
```
    Default AtomCache constructor. Usually stores files in a temp directory, but this can be overriden by setting the PDB_DIR variable at runtime.
    
    See Also:
    UserConfiguration.UserConfiguration()
  - AtomCache
```
public AtomCache(java.lang.String pdbFilePath,
         boolean isSplit)
```
    Creates an instance of an AtomCache that is pointed to the a particular path in the file system.
    
    Parameters:
    pdbFilePath - a directory in the file system to use as a location to cache files.
    isSplit - a flag to indicate if the directory organisation is "split" as on the PDB ftp servers, or if all files are contained in one directory.
  - AtomCache
```
public AtomCache(UserConfiguration config)
```
    Creates a new AtomCache object based on the provided UserConfiguration.
    
    Parameters:
    config - the UserConfiguration to use for this cache.
- Method Detail
  - getAtoms
```
public Atom[] getAtoms(java.lang.String name)
                throws java.io.IOException,
                       StructureException
```
    Returns the CA atoms for the provided name. See getStructure(String) for supported naming conventions.
    
    Parameters:
    name -
    
    Returns:
    an array of Atoms.
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - getAtoms
```
@Deprecated
public Atom[] getAtoms(java.lang.String name,
                         boolean clone)
                throws java.io.IOException,
                       StructureException
```
    Deprecated. does the same as getAtoms(String) ;
    
    Returns the CA atoms for the provided name. See getStructure(String) for supported naming conventions.
    
    Parameters:
    name -
    clone - flag to make sure that the atoms are getting coned
    
    Returns:
    an array of Atoms.
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - getBiologicalAssembly
```
public Structure getBiologicalAssembly(java.lang.String pdbId,
                              int bioAssemblyId,
                              boolean bioAssemblyFallback)
                                throws StructureException,
                                       java.io.IOException
```
    Loads the biological assembly for a given PDB ID and bioAssemblyId. If a bioAssemblyId > 0 is specified, the corresponding biological assembly file will be loaded. Note, the number of available biological unit files varies. Many entries don't have a biological assembly specified (i.e. NMR structures), many entries have only one biological assembly (bioAssemblyId=1), and a few structures have multiple biological assemblies. Set bioAssemblyFallback to true, to download the original PDB file in cases that a biological assembly file is not available.
    
    Parameters:
    pdbId - the PDB ID
    bioAssemblyId - the ID of the biological assembly
    bioAssemblyFallback - if true, try reading original PDB file in case the biological assembly file is not available
    
    Returns:
    a structure object
    
    Throws:
    
    java.io.IOException
    
    StructureException
    Since:
    
    3.2
  - getBiologicalUnit
```
public Structure getBiologicalUnit(java.lang.String pdbId)
                            throws StructureException,
                                   java.io.IOException
```
    Loads the default biological unit (*.pdb1.gz) file. If it is not available, the original PDB file will be loaded, i.e., for NMR structures, where the original files is also the biological assembly.
    
    Parameters:
    pdbId - the PDB ID
    
    Returns:
    a structure object
    
    Throws:
    
    java.io.IOException
    
    StructureException
    Since:
    
    3.2
  - getCachePath
```
public java.lang.String getCachePath()
```
    Returns the path that contains the caching file for utility data, such as domain definitons.
    
    Returns:
  - getFileParsingParams
```
public FileParsingParameters getFileParsingParams()
```
  - getPath
```
public java.lang.String getPath()
```
    Get the path that is used to cache PDB files.
    
    Returns:
    path to a directory
  - getPdpprovider
```
public PDPProvider getPdpprovider()
```
  - getStructure
```
public Structure getStructure(java.lang.String name)
                       throws java.io.IOException,
                              StructureException
```
    Request a Structure based on a name.
```
                Formal specification for how to specify the name:
 
                name     := pdbID
                               | pdbID '.' chainID
                               | pdbID '.' range
                               | scopID
                range         := '('? range (',' range)? ')'?
                               | chainID
                               | chainID '_' resNum '-' resNum
                pdbID         := [0-9][a-zA-Z0-9]{3}
                chainID       := [a-zA-Z0-9]
                scopID        := 'd' pdbID [a-z_][0-9_]
                resNum        := [-+]?[0-9]+[A-Za-z]?
 
 
                Example structures:
                1TIM     #whole structure
                4HHB.C     #single chain
                4GCR.A_1-83     #one domain, by residue number
                3AA0.A,B     #two chains treated as one structure
                d2bq6a1     #scop domain
 
```
    With the additional set of rules:
    - If only a PDB code is provided, the whole structure will be return including ligands, but the first model only (for NMR).
    - Chain IDs are case sensitive, PDB ids are not. To specify a particular chain write as: 4hhb.A or 4HHB.A
    - To specify a SCOP domain write a scopId e.g. d2bq6a1. Some flexibility can be allowed in SCOP domain names, see setStrictSCOP(boolean)
    - URLs are accepted as well
    Parameters:
    name -
    
    Returns:
    a Structure object, or null if name appears improperly formated (eg too short, etc)
    
    Throws:
    
    java.io.IOException - The PDB file cannot be cached due to IO errors
    
    StructureException - The name appeared valid but did not correspond to a structure. Also thrown by some submethods upon errors, eg for poorly formatted subranges.
  - getStructureForDomain
```
public Structure getStructureForDomain(ScopDomain domain)
                                throws java.io.IOException,
                                       StructureException
```
    Returns the representation of a ScopDomain as a BioJava Structure object.
    
    Parameters:
    domain - a SCOP domain
    
    Returns:
    a Structure object
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - getStructureForDomain
```
public Structure getStructureForDomain(ScopDomain domain,
                              ScopDatabase scopDatabase)
                                throws java.io.IOException,
                                       StructureException
```
    Returns the representation of a ScopDomain as a BioJava Structure object.
    
    Parameters:
    domain - a SCOP domain
    scopDatabase - A ScopDatabase to use
    
    Returns:
    a Structure object
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - getStructureForDomain
```
public Structure getStructureForDomain(ScopDomain domain,
                              ScopDatabase scopDatabase,
                              boolean strictLigandHandling)
                                throws java.io.IOException,
                                       StructureException
```
    Returns the representation of a ScopDomain as a BioJava Structure object.
    
    Parameters:
    domain - a SCOP domain
    scopDatabase - A ScopDatabase to use
    strictLigandHandling - If set to false, hetero-atoms are included if and only if they belong to a chain to which the SCOP domain belongs; if set to true, hetero-atoms are included if and only if they are strictly within the definition (residue numbers) of the SCOP domain
    
    Returns:
    a Structure object
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - getStructureForDomain
```
public Structure getStructureForDomain(java.lang.String scopId)
                                throws java.io.IOException,
                                       StructureException
```
    Returns the representation of a ScopDomain as a BioJava Structure object.
    
    Parameters:
    scopId - a SCOP Id
    
    Returns:
    a Structure object
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - getStructureForDomain
```
public Structure getStructureForDomain(java.lang.String scopId,
                              ScopDatabase scopDatabase)
                                throws java.io.IOException,
                                       StructureException
```
    Returns the representation of a ScopDomain as a BioJava Structure object.
    
    Parameters:
    scopId - a SCOP Id
    scopDatabase - A ScopDatabase to use
    
    Returns:
    a Structure object
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - isAutoFetch
```
public boolean isAutoFetch()
```
    Does the cache automatically download files that are missing from the local installation from the PDB FTP site?
    
    Returns:
    flag
  - isFetchCurrent
```
public boolean isFetchCurrent()
```
    N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
    
    Returns:
    the fetchCurrent
  - isFetchFileEvenIfObsolete
```
public boolean isFetchFileEvenIfObsolete()
```
    forces the cache to fetch the file if its status is OBSOLETE. This feature has a higher priority than setFetchCurrent(boolean).
    N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
    
    Returns:
    the fetchFileEvenIfObsolete
    Since:
    
    3.0.2
    
    See Also:
    fetchCurrent
  - isSplit
```
public boolean isSplit()
```
    Is the organization of files within the directory split, as on the PDB FTP servers, or are all files contained in one directory.
    
    Returns:
    flag
  - isStrictSCOP
```
public boolean isStrictSCOP()
```
    Reports whether strict scop naming will be enforced, or whether this AtomCache should try to guess some simple variants on scop domains.
    
    Returns:
    true if scop names should be used strictly with no guessing
  - notifyShutdown
```
public void notifyShutdown()
```
    Send a signal to the cache that the system is shutting down. Notifies underlying SerializableCache instances to flush themselves...
  - setAutoFetch
```
public void setAutoFetch(boolean autoFetch)
```
    Does the cache automatically download files that are missing from the local installation from the PDB FTP site?
    
    Parameters:
    autoFetch - flag
  - setCachePath
```
public void setCachePath(java.lang.String cachePath)
```
    set the location at which utility data should be cached.
    
    Parameters:
    cachePath -
  - setFetchCurrent
```
public void setFetchCurrent(boolean fetchNewestCurrent)
```
    if enabled, the reader searches for the newest possible PDB ID, if not present in he local installation. The setFetchFileEvenIfObsolete(boolean) function has a higher priority than this function.
    N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
    
    Parameters:
    fetchCurrent - the fetchCurrent to set
    Since:
    
    3.0.2
    
    See Also:
    setFetchFileEvenIfObsolete(boolean)
  - setFetchFileEvenIfObsolete
```
public void setFetchFileEvenIfObsolete(boolean fetchFileEvenIfObsolete)
```
    N.B. This feature won't work unless the structure wasn't found & autoFetch is set to true.
    
    Parameters:
    fetchFileEvenIfObsolete - the fetchFileEvenIfObsolete to set
  - setFileParsingParams
```
public void setFileParsingParams(FileParsingParameters params)
```
  - setPath
```
public void setPath(java.lang.String path)
```
    Set the path that is used to cache PDB files.
    
    Parameters:
    path - to a directory
  - setPdpprovider
```
public void setPdpprovider(PDPProvider pdpprovider)
```
  - setSplit
```
public void setSplit(boolean isSplit)
```
    Is the organization of files within the directory split, as on the PDB FTP servers, or are all files contained in one directory.
    
    Parameters:
    isSplit - flag
  - setStrictSCOP
```
public void setStrictSCOP(boolean strictSCOP)
```
    When strictSCOP is enabled, SCOP domain identifiers (eg 'd1gbga_') are matched literally to the SCOP database. When disabled, some simple mistakes are corrected automatically. For instance, the invalid identifier 'd1gbg__' would be corrected to 'd1gbga_' automatically.
    
    Parameters:
    strictSCOP - Indicates whether strict scop names should be used.
  - isUseMmCif
```
public boolean isUseMmCif()
```
    Returns:
    the useMmCif
  - setUseMmCif
```
public void setUseMmCif(boolean useMmCif)
```
    Parameters:
    useMmCif - the useMmCif to set
  - getStructureForCathDomain
```
public Structure getStructureForCathDomain(StructureName structureName)
                                    throws java.io.IOException,
                                           StructureException
```
    Returns a Structure corresponding to the CATH identifier supplied in structureName, using the the CathDatabase at CathFactory.getCathDatabase().
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - getStructureForCathDomain
```
public Structure getStructureForCathDomain(StructureName structureName,
                                  CathDatabase cathInstall)
                                    throws java.io.IOException,
                                           StructureException
```
    Returns a Structure corresponding to the CATH identifier supplied in structureName, using the specified CathDatabase.
    
    Throws:
    
    java.io.IOException
    
    StructureException
  - flagLoading
```
protected void flagLoading(java.lang.String name)
```
  - flagLoadingFinished
```
protected void flagLoadingFinished(java.lang.String name)
```
  - loadStructureFromCifByPdbId
```
protected Structure loadStructureFromCifByPdbId(java.lang.String pdbId)
                                         throws StructureException
```
    Throws:
    
    StructureException
  - loadStructureFromPdbByPdbId
```
protected Structure loadStructureFromPdbByPdbId(java.lang.String pdbId)
                                         throws StructureException
```
    Throws:
    
    StructureException

Class AtomCache

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BIOL_ASSEMBLY_IDENTIFIER

CHAIN_NR_SYMBOL

CHAIN_SPLIT_SYMBOL

PDP_DOMAIN_IDENTIFIER

scopIDregex

UNDERSCORE

params

pdpprovider

Constructor Detail

AtomCache

AtomCache

AtomCache

Method Detail

getAtoms

getAtoms

getBiologicalAssembly

getBiologicalUnit

getCachePath

getFileParsingParams

getPath

getPdpprovider

getStructure

getStructureForDomain

getStructureForDomain

getStructureForDomain

getStructureForDomain

getStructureForDomain

isAutoFetch

isFetchCurrent

isFetchFileEvenIfObsolete

isSplit

isStrictSCOP

notifyShutdown

setAutoFetch

setCachePath

setFetchCurrent

setFetchFileEvenIfObsolete

setFileParsingParams

setPath

setPdpprovider

setSplit

setStrictSCOP

isUseMmCif

setUseMmCif

getStructureForCathDomain

getStructureForCathDomain

flagLoading

flagLoadingFinished

loadStructureFromCifByPdbId

loadStructureFromPdbByPdbId