Class 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, 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 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 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​(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 interface StructureIOFile
        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 interface StructureIOFile
        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()
      • 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
      • 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​(java.lang.String filename)
                               throws java.io.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:
        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 interface StructureIOFile
        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 interface StructureProvider
        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 is LocalPDBDirectory.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, 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 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