org.biojava.nbio.structure.io

Class LocalPDBDirectory

java.lang.Object

org.biojava.nbio.structure.io.LocalPDBDirectory

All Implemented Interfaces:

StructureIOFile, StructureProvider

Direct Known Subclasses:

MMCIFFileReader, 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 MMCIFFileReader. 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 and 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 and Description
static String	DEFAULT_PDB_FILE_SERVER The default server name, prefixed by the protocol string (http:// 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 and Description
LocalPDBDirectory()
LocalPDBDirectory(String path) Subclasses should provide default and single-string constructors.

Method Summary

Methods

Modifier and Type	Method and 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)
void	clearExtensions() clear the supported file extensions
boolean	deleteStructure(String pdbId) Attempts to delete all versions of a structure from the local directory.
protected File	downloadStructure(String 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(String 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
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
protected void	initPaths() Should be called whenever any of the path variables change.
boolean	isAutoFetch() Deprecated. Use getFetchBehavior()
void	prefetchStructure(String pdbId) Download a structure, but don't parse it yet or store it in memory.
void	setAutoFetch(boolean autoFetch) Deprecated. Use #setFetchBehavior()
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:// 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

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

isAutoFetch

@Deprecated
public boolean isAutoFetch()

Deprecated. Use getFetchBehavior()

setAutoFetch

@Deprecated
public void setAutoFetch(boolean autoFetch)

Deprecated. Use #setFetchBehavior()

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

Description copied from interface: StructureProvider

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(String 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 -

Returns:

True if one or more files were deleted

Throws:

IOException - if the file cannot be deleted

downloadStructure

protected File downloadStructure(String 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

checkFileExists

protected boolean checkFileExists(String 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 "http://ftp.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