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

  • Field Details

    • 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:

    • PDB_FILE_SERVER_PROPERTY

      public static final String PDB_FILE_SERVER_PROPERTY
      See Also:

    • 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:

  • 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:

    • 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