java.lang.Object
- org.biojava.nbio.structure.io.LocalPDBDirectory

All Implemented Interfaces:

StructureIOFile, StructureProvider

Direct Known Subclasses:

BcifFileReader, CifFileReader, MMTFFileReader, PDBFileReader
```
public abstract class LocalPDBDirectory
extends Object
implements StructureIOFile
```
Superclass for classes which download and interact with the PDB's FTP server, specifically PDBFileReader and CifFileReader. The basic functionality of downloading structure files from the FTP site is gathered here, making the child classes responsible for only the specific paths and file formats needed.

Author:

Spencer Bliven

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`LocalPDBDirectory.FetchBehavior`	Controls when the class should fetch files from the ftp server
`static class`	`LocalPDBDirectory.ObsoleteBehavior`	Behaviors for when an obsolete structure is requested.

Field Summary

Fields
Modifier and Type	Field	Description
`static String`	`DEFAULT_BCIF_FILE_SERVER`	The default server to retrieve BinaryCIF files.
`static String`	`DEFAULT_PDB_FILE_SERVER`	The default server name, prefixed by the protocol string (http://, https:// or ftp://).
`static long`	`LAST_REMEDIATION_DATE`	Date of the latest PDB file remediation
`protected static String`	`lineSplit`
`static long`	`MIN_PDB_FILE_SIZE`	Minimum size for a valid structure file (CIF or PDB), in bytes
`static String`	`PDB_FILE_SERVER_PROPERTY`

Constructor Summary

Constructors
Constructor Description

LocalPDBDirectory()

LocalPDBDirectory(String path)
Subclasses should provide default and single-string constructors.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method	Description
`void`	`addExtension(String s)`	define supported file extensions compressed extensions .Z,.gz do not need to be specified they are dealt with automatically.
`protected boolean`	`checkFileExists(String pdbId)`
`protected boolean`	`checkFileExists(PdbId pdbId)`
`void`	`clearExtensions()`	clear the supported file extensions
`boolean`	`deleteStructure(String pdbId)`	Attempts to delete all versions of a structure from the local directory.
`boolean`	`deleteStructure(PdbId pdbId)`	Attempts to delete all versions of a structure from the local directory.
`protected File`	`downloadStructure(PdbId pdbId)`	Downloads an MMCIF file from the PDB to the local path
`protected File`	`getDir(String pdbId, boolean obsolete)`	Gets the directory in which the file for a given MMCIF file would live, creating it if necessary.
`List<String>`	`getExtensions()`	Returns a list of extensions supported by this class
`LocalPDBDirectory.FetchBehavior`	`getFetchBehavior()`	Get the behavior for fetching files from the server
`protected abstract String`	`getFilename(String pdbId)`	Converts a PDB ID into a filename with the proper extension
`FileParsingParameters`	`getFileParsingParameters()`	Get the parameters that should be used for file parsing
`protected InputStream`	`getInputStream(PdbId pdbId)`	Load or download the specified structure and return it as an InputStream for direct parsing.
`File`	`getLocalFile(String pdbId)`	Searches for previously downloaded files
`File`	`getLocalFile(PdbId pdbId)`	Searches for previously downloaded files
`LocalPDBDirectory.ObsoleteBehavior`	`getObsoleteBehavior()`	Returns how this instance deals with obsolete entries.
`protected abstract String[]`	`getObsoleteDirPath()`	Location of obsolete files within the directory, as an array of paths.
`String`	`getPath()`	Returns the path value.
`static String`	`getServerName()`	Return the String with the PDB server name, including the leading protocol String (http:// or ftp://).
`protected abstract String[]`	`getSplitDirPath()`	Location of split files within the directory, as an array of paths.
`Structure`	`getStructure(File filename)`	Read file from File and returns a Structure object.
`abstract Structure`	`getStructure(InputStream inStream)`	Handles the actual parsing of the file into a Structure object.
`Structure`	`getStructure(String filename)`	Open filename and return a Structure object.
`Structure`	`getStructure(URL u)`
`Structure`	`getStructureById(String pdbId)`	Get the structure for a PDB ID
`Structure`	`getStructureById(PdbId pdbId)`	Get the structure for a PDB ID
`protected void`	`initPaths()`	Should be called whenever any of the path variables change.
`void`	`prefetchStructure(String pdbId)`	Download a structure, but don't parse it yet or store it in memory.
`void`	`setFetchBehavior(LocalPDBDirectory.FetchBehavior fetchBehavior)`	Set the behavior for fetching files from the server.
`void`	`setFileParsingParameters(FileParsingParameters params)`	Set the parameters that should be used for file parsing
`void`	`setObsoleteBehavior(LocalPDBDirectory.ObsoleteBehavior behavior)`	[Optional] This method changes the behavior when obsolete entries are requested.
`void`	`setPath(String p)`	Sets the path for the directory where PDB files are read/written

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

- Field Detail
  - DEFAULT_PDB_FILE_SERVER
```
public static final String DEFAULT_PDB_FILE_SERVER
```
    The default server name, prefixed by the protocol string (http://, https:// or ftp://). Note that we don't support file stamp retrieving for ftp protocol, thus some of the fetch modes will not work properly with ftp protocol
    
    See Also:
    
    Constant Field Values
  - PDB_FILE_SERVER_PROPERTY
```
public static final String PDB_FILE_SERVER_PROPERTY
```
    See Also:
    
    Constant Field Values
  - DEFAULT_BCIF_FILE_SERVER
```
public static final String DEFAULT_BCIF_FILE_SERVER
```
    The default server to retrieve BinaryCIF files.
    
    See Also:
    
    Constant Field Values
  - LAST_REMEDIATION_DATE
```
public static final long LAST_REMEDIATION_DATE
```
    Date of the latest PDB file remediation
  - lineSplit
```
protected static final String lineSplit
```
  - MIN_PDB_FILE_SIZE
```
public static final long MIN_PDB_FILE_SIZE
```
    Minimum size for a valid structure file (CIF or PDB), in bytes
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - LocalPDBDirectory
```
public LocalPDBDirectory(String path)
```
    Subclasses should provide default and single-string constructors. They should use addExtension(String) to add one or more extensions.
    If path is null, initialize using the system property/environment variable UserConfiguration.PDB_DIR.
    
    Parameters:
    
    path - Path to the PDB file directory
  - LocalPDBDirectory
```
public LocalPDBDirectory()
```
- Method Detail
  - setPath
```
public void setPath(String p)
```
    Sets the path for the directory where PDB files are read/written
  - getPath
```
public String getPath()
```
    Returns the path value.
    
    Returns:
    
    a String representing the path value
    
    See Also:
    
    setPath(java.lang.String)
  - addExtension
```
public void addExtension(String s)
```
    define supported file extensions compressed extensions .Z,.gz do not need to be specified they are dealt with automatically.
    
    Specified by:
    
    addExtension in interface StructureIOFile
    
    Parameters:
    
    s - a String ...
  - getExtensions
```
public List<String> getExtensions()
```
    Description copied from interface: StructureIOFile
    
    Returns a list of extensions supported by this class
    
    Specified by:
    
    getExtensions in interface StructureIOFile
    
    Returns:
    
    a (potentially empty) list of strings
  - clearExtensions
```
public void clearExtensions()
```
    clear the supported file extensions
  - setFileParsingParameters
```
public void setFileParsingParameters(FileParsingParameters params)
```
    Description copied from interface: StructureProvider
    
    Set the parameters that should be used for file parsing
    
    Specified by:
    
    setFileParsingParameters in interface StructureProvider
    
    Parameters:
    
    params - FileParsingParameters
  - getFileParsingParameters
```
public FileParsingParameters getFileParsingParameters()
```
    Description copied from interface: StructureProvider
    
    Get the parameters that should be used for file parsing
    
    Specified by:
    
    getFileParsingParameters in interface StructureProvider
    
    Returns:
    
    the FileParsingParameters that are configuring the behavior of the parser
  - setObsoleteBehavior
```
public void setObsoleteBehavior(LocalPDBDirectory.ObsoleteBehavior behavior)
```
    [Optional] This method changes the behavior when obsolete entries are requested. Current behaviors are:
    
    THROW_EXCEPTION Throw a StructureException (the default)
    FETCH_OBSOLETE Load the requested ID from the PDB's obsolete repository
    FETCH_CURRENT Load the most recent version of the requested structure
    This setting may be silently ignored by implementations which do not have access to the server to determine whether an entry is obsolete, such as if #isAutoFetch() is false. Note that an obsolete entry may still be returned even this is FETCH_CURRENT if the entry is found locally.
    Parameters:
    
    fetchFileEvenIfObsolete - Whether to fetch obsolete records
    
    Since:
    
    4.0.0
    
    See Also:
    
    #setFetchCurrent(boolean)
  - getObsoleteBehavior
```
public LocalPDBDirectory.ObsoleteBehavior getObsoleteBehavior()
```
    Returns how this instance deals with obsolete entries. Note that this setting may be ignored by some implementations or in some situations, such as when #isAutoFetch() is false.
    For most implementations, the default value is THROW_EXCEPTION.
    
    Returns:
    
    The ObsoleteBehavior
    
    Since:
    
    4.0.0
  - getFetchBehavior
```
public LocalPDBDirectory.FetchBehavior getFetchBehavior()
```
    Get the behavior for fetching files from the server
    
    Returns:
  - setFetchBehavior
```
public void setFetchBehavior(LocalPDBDirectory.FetchBehavior fetchBehavior)
```
    Set the behavior for fetching files from the server. This replaces the #setAutoFetch(boolean) method with a more extensive set of options.
    
    Parameters:
    
    fetchBehavior -
  - getStructure
```
public Structure getStructure(String filename)
                       throws IOException
```
    Description copied from interface: StructureIOFile
    
    Open filename and return a Structure object. Not to be confused with StructureProvider.getStructureById(String)
    
    Specified by:
    
    getStructure in interface StructureIOFile
    
    Parameters:
    
    filename - The path to the file. Must be the correct format for the implementing class.
    
    Returns:
    
    a Structure object
    
    Throws:
    
    IOException - ...
  - getStructure
```
public Structure getStructure(URL u)
                       throws IOException
```
    Throws:
    
    IOException
  - getStructure
```
public Structure getStructure(File filename)
                       throws IOException
```
    Description copied from interface: StructureIOFile
    
    Read file from File and returns a Structure object.
    
    Specified by:
    
    getStructure in interface StructureIOFile
    
    Parameters:
    
    filename - file containing the structure. Must be the correct format for the implementing class
    
    Returns:
    
    a Structure object
    
    Throws:
    
    IOException - ...
  - getStructureById
```
public Structure getStructureById(String pdbId)
                           throws IOException
```
    Get the structure for a PDB ID
    
    Specified by:
    
    getStructureById in interface StructureProvider
    
    Returns:
    
    Throws:
    
    IOException
  - getStructureById
```
public Structure getStructureById(PdbId pdbId)
                           throws IOException
```
    Get the structure for a PDB ID
    
    Specified by:
    
    getStructureById in interface StructureProvider
    
    Returns:
    
    Throws:
    
    IOException
  - getStructure
```
public abstract Structure getStructure(InputStream inStream)
                                throws IOException
```
    Handles the actual parsing of the file into a Structure object.
    
    Parameters:
    
    inStream -
    
    Returns:
    
    Throws:
    
    IOException
  - getInputStream
```
protected InputStream getInputStream(PdbId pdbId)
                              throws IOException
```
    Load or download the specified structure and return it as an InputStream for direct parsing.
    
    Parameters:
    
    pdbId -
    
    Returns:
    
    Throws:
    
    IOException
  - prefetchStructure
```
public void prefetchStructure(String pdbId)
                       throws IOException
```
    Download a structure, but don't parse it yet or store it in memory. Used to pre-fetch large numbers of structures.
    
    Parameters:
    
    pdbId -
    
    Throws:
    
    IOException
  - deleteStructure
```
public boolean deleteStructure(String pdbId)
                        throws IOException
```
    Attempts to delete all versions of a structure from the local directory.
    
    Parameters:
    
    pdbId - a String representing the PDB ID.
    
    Returns:
    
    True if one or more files were deleted
    
    Throws:
    
    IOException - if the file cannot be deleted
  - deleteStructure
```
public boolean deleteStructure(PdbId pdbId)
                        throws IOException
```
    Attempts to delete all versions of a structure from the local directory.
    
    Parameters:
    
    pdbId - The PDB ID
    
    Returns:
    
    True if one or more files were deleted
    
    Throws:
    
    IOException - if the file cannot be deleted
  - downloadStructure
```
protected File downloadStructure(PdbId pdbId)
                          throws IOException
```
    Downloads an MMCIF file from the PDB to the local path
    
    Parameters:
    
    pdbId -
    
    Returns:
    
    The file, or null if it was unavailable for download
    
    Throws:
    
    IOException - for errors downloading or writing, or if the fetchBehavior is LocalPDBDirectory.FetchBehavior.LOCAL_ONLY
  - getDir
```
protected File getDir(String pdbId,
                      boolean obsolete)
```
    Gets the directory in which the file for a given MMCIF file would live, creating it if necessary. The obsolete parameter is necessary to avoid additional server queries.
    
    Parameters:
    
    pdbId -
    
    obsolete - Whether the pdbId is obsolete or not
    
    Returns:
    
    File pointing to the directory,
  - getLocalFile
```
public File getLocalFile(String pdbId)
                  throws IOException
```
    Searches for previously downloaded files
    
    Parameters:
    
    pdbId -
    
    Returns:
    
    A file pointing to the existing file, or null if not found
    
    Throws:
    
    IOException - If the file exists but is empty and can't be deleted
  - getLocalFile
```
public File getLocalFile(PdbId pdbId)
                  throws IOException
```
    Searches for previously downloaded files
    
    Parameters:
    
    pdbId -
    
    Returns:
    
    A file pointing to the existing file, or null if not found
    
    Throws:
    
    IOException - If the file exists but is empty and can't be deleted
  - checkFileExists
```
protected boolean checkFileExists(String pdbId)
```
  - checkFileExists
```
protected boolean checkFileExists(PdbId pdbId)
```
  - getServerName
```
public static String getServerName()
```
    Return the String with the PDB server name, including the leading protocol String (http:// or ftp://). The server name will be by default the value "https://files.wwpdb.org" or the one read from system property "PDB.FILE.SERVER"
    
    Returns:
    
    the server name including the leading protocol string
  - initPaths
```
protected void initPaths()
```
    Should be called whenever any of the path variables change. Thus, if getSplitDirPath() or getObsoleteDirPath() depend on anything, they should call this function when that thing changes (possibly including at the end of the constructor).
  - getFilename
```
protected abstract String getFilename(String pdbId)
```
    Converts a PDB ID into a filename with the proper extension
    
    Parameters:
    
    pdbId -
    
    Returns:
    
    The filename, e.g. "4hhb.pdb.gz"
  - getSplitDirPath
```
protected abstract String[] getSplitDirPath()
```
    Location of split files within the directory, as an array of paths. These will be joined with either slashes (for the URL) or the file separator (for directories). The returned results should be constant, to allow for caching.
    
    Returns:
    
    A list of directories, relative to the /pub/pdb directory on the server
  - getObsoleteDirPath
```
protected abstract String[] getObsoleteDirPath()
```
    Location of obsolete files within the directory, as an array of paths. These will be joined with either slashes (for the URL) or the file separator (for directories). The returned results should be constant, to allow for caching.
    
    Returns:
    
    A list of directories, relative to the /pub/pdb directory on the server

Constructor	Description
`LocalPDBDirectory()`
`LocalPDBDirectory(String path)`	Subclasses should provide default and single-string constructors.

Class LocalPDBDirectory

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_PDB_FILE_SERVER

PDB_FILE_SERVER_PROPERTY

DEFAULT_BCIF_FILE_SERVER

LAST_REMEDIATION_DATE

lineSplit

MIN_PDB_FILE_SIZE

Constructor Detail

LocalPDBDirectory

LocalPDBDirectory

Method Detail

setPath

getPath

addExtension

getExtensions

clearExtensions

setFileParsingParameters

getFileParsingParameters

setObsoleteBehavior

getObsoleteBehavior

getFetchBehavior

setFetchBehavior

getStructure

getStructure

getStructure

getStructureById

getStructureById

getStructure

getInputStream

prefetchStructure

deleteStructure

deleteStructure

downloadStructure

getDir

getLocalFile

getLocalFile

checkFileExists

checkFileExists

getServerName

initPaths

getFilename

getSplitDirPath

getObsoleteDirPath