Package org.biojava.nbio.structure.io

Class LocalPDBDirectory

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 enum	LocalPDBDirectory.FetchBehavior	Controls when the class should fetch files from the ftp server
static enum	LocalPDBDirectory.ObsoleteBehavior	Behaviors for when an obsolete structure is requested.

Field Summary

Fields

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

Constructor Summary

Constructors

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

Method Summary

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 Details

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

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 Details

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 Details

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 certain LocalPDBDirectory.FetchBehaviors. Note that an obsolete entry may still be returned even this is FETCH_CURRENT if the entry is found locally.

Parameters:

behavior - Whether to fetch obsolete records

Since:

4.0.0

See Also:

• setFetchBehavior(FetchBehavior)

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 certain LocalPDBDirectory.FetchBehaviors.

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.

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

Parameters:

pdbId -

Returns:

Throws:

IOException

getStructureById

public Structure getStructureById(PdbId pdbId)
                           throws IOException

Get the structure for a PDB ID

Specified by:

getStructureById in interface StructureProvider

Parameters:

pdbId -

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 - in cases of file I/O, including failure to download a healthy (non-corrupted) file.

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 - in cases of file I/O, including failure to download a healthy (non-corrupted) file.

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