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:
MMCIFFileReader
,PDBFileReader
public abstract class LocalPDBDirectory extends java.lang.Object implements StructureIOFile
Superclass for classes which download and interact with the PDB's FTP server, specificallyPDBFileReader
andMMCIFFileReader
. 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 serverstatic class
LocalPDBDirectory.ObsoleteBehavior
Behaviors for when an obsolete structure is requested.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.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 remediationprotected static java.lang.String
lineSplit
static long
MIN_PDB_FILE_SIZE
Minimum size for a valid structure file (CIF or PDB), in bytesstatic java.lang.String
PDB_FILE_SERVER_PROPERTY
-
Constructor Summary
Constructors Constructor Description LocalPDBDirectory()
LocalPDBDirectory(java.lang.String path)
Subclasses should provide default and single-string constructors.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
addExtension(java.lang.String s)
define supported file extensions compressed extensions .Z,.gz do not need to be specified they are dealt with automatically.protected boolean
checkFileExists(java.lang.String pdbId)
void
clearExtensions()
clear the supported file extensionsboolean
deleteStructure(java.lang.String pdbId)
Attempts to delete all versions of a structure from the local directory.protected java.io.File
downloadStructure(java.lang.String pdbId)
Downloads an MMCIF file from the PDB to the local pathprotected java.io.File
getDir(java.lang.String pdbId, boolean obsolete)
Gets the directory in which the file for a given MMCIF file would live, creating it if necessary.java.util.List<java.lang.String>
getExtensions()
Returns a list of extensions supported by this classLocalPDBDirectory.FetchBehavior
getFetchBehavior()
Get the behavior for fetching files from the serverprotected abstract java.lang.String
getFilename(java.lang.String pdbId)
Converts a PDB ID into a filename with the proper extensionFileParsingParameters
getFileParsingParameters()
Get the parameters that should be used for file parsingprotected java.io.InputStream
getInputStream(java.lang.String pdbId)
Load or download the specified structure and return it as an InputStream for direct parsing.java.io.File
getLocalFile(java.lang.String pdbId)
Searches for previously downloaded filesLocalPDBDirectory.ObsoleteBehavior
getObsoleteBehavior()
Returns how this instance deals with obsolete entries.protected abstract java.lang.String[]
getObsoleteDirPath()
Location of obsolete files within the directory, as an array of paths.java.lang.String
getPath()
Returns the path value.static java.lang.String
getServerName()
Return the String with the PDB server name, including the leading protocol String (http:// or ftp://).protected abstract java.lang.String[]
getSplitDirPath()
Location of split files within the directory, as an array of paths.Structure
getStructure(java.io.File filename)
Read file from File and returns a Structure object.abstract Structure
getStructure(java.io.InputStream inStream)
Handles the actual parsing of the file into a Structure object.Structure
getStructure(java.lang.String filename)
Open filename and return a Structure object.Structure
getStructure(java.net.URL u)
Structure
getStructureById(java.lang.String pdbId)
get the structure for a PDB IDprotected void
initPaths()
Should be called whenever any of the path variables change.boolean
isAutoFetch()
Deprecated.void
prefetchStructure(java.lang.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 parsingvoid
setObsoleteBehavior(LocalPDBDirectory.ObsoleteBehavior behavior)
[Optional] This method changes the behavior when obsolete entries are requested.void
setPath(java.lang.String p)
Sets the path for the directory where PDB files are read/written
-
-
-
Field Detail
-
DEFAULT_PDB_FILE_SERVER
public static final java.lang.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 java.lang.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 java.lang.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(java.lang.String path)
Subclasses should provide default and single-string constructors. They should useaddExtension(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(java.lang.String p)
Sets the path for the directory where PDB files are read/written
-
getPath
public java.lang.String getPath()
Returns the path value.- Returns:
- a String representing the path value
- See Also:
setPath(java.lang.String)
-
addExtension
public void addExtension(java.lang.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 interfaceStructureIOFile
- Parameters:
s
- a String ...
-
getExtensions
public java.util.List<java.lang.String> getExtensions()
Description copied from interface:StructureIOFile
Returns a list of extensions supported by this class- Specified by:
getExtensions
in interfaceStructureIOFile
- Returns:
- a (potentially empty) list of strings
-
clearExtensions
public void clearExtensions()
clear the supported file extensions
-
isAutoFetch
@Deprecated public boolean isAutoFetch()
Deprecated.
-
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 interfaceStructureProvider
- 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 interfaceStructureProvider
- 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 aStructureException
(the default)FETCH_OBSOLETE
Load the requested ID from the PDB's obsolete repositoryFETCH_CURRENT
Load the most recent version of the requested structureThis 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 whenisAutoFetch()
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 thesetAutoFetch(boolean)
method with a more extensive set of options.- Parameters:
fetchBehavior
-
-
getStructure
public Structure getStructure(java.lang.String filename) throws java.io.IOException
Description copied from interface:StructureIOFile
Open filename and return a Structure object. Not to be confused withStructureProvider.getStructureById(String)
- Specified by:
getStructure
in interfaceStructureIOFile
- Parameters:
filename
- The path to the file. Must be the correct format for the implementing class.- Returns:
- a Structure object
- Throws:
java.io.IOException
- ...
-
getStructure
public Structure getStructure(java.net.URL u) throws java.io.IOException
- Throws:
java.io.IOException
-
getStructure
public Structure getStructure(java.io.File filename) throws java.io.IOException
Description copied from interface:StructureIOFile
Read file from File and returns a Structure object.- Specified by:
getStructure
in interfaceStructureIOFile
- Parameters:
filename
- file containing the structure. Must be the correct format for the implementing class- Returns:
- a Structure object
- Throws:
java.io.IOException
- ...
-
getStructureById
public Structure getStructureById(java.lang.String pdbId) throws java.io.IOException
Description copied from interface:StructureProvider
get the structure for a PDB ID- Specified by:
getStructureById
in interfaceStructureProvider
- Returns:
- Throws:
java.io.IOException
-
getStructure
public abstract Structure getStructure(java.io.InputStream inStream) throws java.io.IOException
Handles the actual parsing of the file into a Structure object.- Parameters:
inStream
-- Returns:
- Throws:
java.io.IOException
-
getInputStream
protected java.io.InputStream getInputStream(java.lang.String pdbId) throws java.io.IOException
Load or download the specified structure and return it as an InputStream for direct parsing.- Parameters:
pdbId
-- Returns:
- Throws:
java.io.IOException
-
prefetchStructure
public void prefetchStructure(java.lang.String pdbId) throws java.io.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:
java.io.IOException
-
deleteStructure
public boolean deleteStructure(java.lang.String pdbId) throws java.io.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:
java.io.IOException
- if the file cannot be deleted
-
downloadStructure
protected java.io.File downloadStructure(java.lang.String pdbId) throws java.io.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:
java.io.IOException
- for errors downloading or writing, or if the fetchBehavior isLocalPDBDirectory.FetchBehavior.LOCAL_ONLY
-
getDir
protected java.io.File getDir(java.lang.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 java.io.File getLocalFile(java.lang.String pdbId) throws java.io.IOException
Searches for previously downloaded files- Parameters:
pdbId
-- Returns:
- A file pointing to the existing file, or null if not found
- Throws:
java.io.IOException
- If the file exists but is empty and can't be deleted
-
checkFileExists
protected boolean checkFileExists(java.lang.String pdbId)
-
getServerName
public static java.lang.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, ifgetSplitDirPath()
orgetObsoleteDirPath()
depend on anything, they should call this function when that thing changes (possibly including at the end of the constructor).
-
getFilename
protected abstract java.lang.String getFilename(java.lang.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 java.lang.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 java.lang.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
-
-