Package org.biojava.nbio.structure.io.density

Class AbstractDensityMapProvider

java.lang.Object
org.biojava.nbio.structure.io.density.AbstractDensityMapProvider
All Implemented Interfaces:
DensityMapProvider
Direct Known Subclasses:
EmdbMapProvider, PdbeCcp4MapProvider, VolumeServerProvider, WwpdbMapCoefficientsProvider
public abstract class AbstractDensityMapProvider extends Object implements DensityMapProvider
Shared machinery for the concrete density map providers: cache lookup, download with validation, size limiting and format sanity checking.
Since:
7.3.0
Author:
Amr ALHOSSARY

  • Field Details

    • MIN_DENSITY_FILE_SIZE

      public static final long MIN_DENSITY_FILE_SIZE
      Anything smaller than this is not a usable map. Density servers answer with a short body rather than an error status when they have nothing, so a size floor is a necessary part of deciding whether a download succeeded.
      See Also:

  • Constructor Details

    • AbstractDensityMapProvider

      protected AbstractDensityMapProvider(File cacheRoot)
      Parameters:
      cacheRoot - the BioJava cache directory that the density directory sits in

  • Method Details

    • getCacheRoot

      public File getCacheRoot()
      Returns:
      the BioJava cache directory

    • setCacheRoot

      public void setCacheRoot(File cacheRoot)
      Parameters:
      cacheRoot - the BioJava cache directory

    • getFetchBehavior

      public LocalPDBDirectory.FetchBehavior getFetchBehavior()
      Returns:
      how aggressively this provider re-fetches

    • setFetchBehavior

      public void setFetchBehavior(LocalPDBDirectory.FetchBehavior fetchBehavior)
      Parameters:
      fetchBehavior - how aggressively to re-fetch

    • getMaxDownloadBytes

      public long getMaxDownloadBytes()
      Returns:
      the download size limit in bytes, or 0 for no limit

    • setMaxDownloadBytes

      public void setMaxDownloadBytes(long maxDownloadBytes)
      Parameters:
      maxDownloadBytes - the download size limit in bytes, or 0 for no limit

    • supports

      public boolean supports(DensityMapKind kind)
      Description copied from interface: DensityMapProvider
      Whether this provider can serve a given kind of map at all. Used to skip requests that could not possibly succeed, such as asking an X-ray map service for a cryo-EM map.
      Specified by:
      supports in interface DensityMapProvider
      Parameters:
      kind - the kind of map wanted
      Returns:
      true if it is worth trying

    • urlId

      protected String urlId(PdbId pdbId)
      The identifier spelling to put into a URL: four characters and lower case where the entry has a short form.
      Parameters:
      pdbId - the entry
      Returns:
      the identifier for use in a URL

    • effectiveFetchBehavior

      protected LocalPDBDirectory.FetchBehavior effectiveFetchBehavior(DensityMapRequest request)
      The effective fetch behaviour for a request, preferring the request's own setting over this provider's.
      Parameters:
      request - the request
      Returns:
      the behaviour to apply

    • effectiveMaxBytes

      protected long effectiveMaxBytes(DensityMapRequest request)
      The effective size limit for a request, preferring the request's own setting.
      Parameters:
      request - the request
      Returns:
      the limit in bytes, or 0 for no limit

    • effectiveCacheRoot

      protected File effectiveCacheRoot(DensityMapRequest request)
      The cache directory to use for a request, preferring the request's override.
      Parameters:
      request - the request
      Returns:
      the cache directory

    • obtain

      protected DensityMapResult obtain(DensityMapRequest request, URL url, File target, DensityMapKind kind, String emdbId, Double contourLevel, Double sigma) throws IOException
      Obtains a map, serving it from the cache when the fetch behaviour permits and downloading it otherwise.
      Parameters:
      request - what was asked for
      url - where to fetch from
      target - where to cache it
      kind - the concrete kind of map being fetched
      emdbId - the EMDB entry, if this is an EM map; otherwise null
      contourLevel - the author-recommended contour level, or null
      sigma - the map RMS deviation, or null
      Returns:
      the result, or null if the source has nothing for this entry
      Throws:
      IOException - on transport failure

    • isCacheUsable

      protected boolean isCacheUsable(File target, URL url, LocalPDBDirectory.FetchBehavior behavior)
      Whether a cached file may be used as-is.
      Parameters:
      target - the cached file
      url - where it came from
      behavior - the fetch behaviour in force
      Returns:
      true if the cached file should be served

    • isPlausibleMap

      protected boolean isPlausibleMap(File file)
      Checks that a file looks like the format this provider delivers. Only the CCP4/MRC formats carry a recognisable stamp; the others are accepted on size alone.
      Parameters:
      file - the file to check
      Returns:
      true if the file is plausibly a map of this format

    • enforceSizeLimit

      protected void enforceSizeLimit(URL url, long maxBytes, DensityMapRequest request) throws DensityMapTooLargeException
      Refuses a download whose declared size exceeds the limit, before any of the body is transferred.
      Parameters:
      url - the resource
      maxBytes - the limit, or 0 for no limit
      request - the request being served, used for reporting
      Throws:
      DensityMapTooLargeException - if the resource is too large

    • reportTooLarge

      protected void reportTooLarge(URL url, long size, long maxBytes, DensityMapRequest request)
      Announces that a map was skipped for being too large.

      This is reported through the logger and on both standard output and standard error. A user who asked for a map and silently got a coarser one from another source deserves to be told why, and a library log configuration that discards warnings should not be able to hide it.

      Parameters:
      url - the resource that was skipped
      size - its size in bytes
      maxBytes - the limit in bytes
      request - the request being served

    • declaredSize

      protected long declaredSize(URL url)
      The Content-Length a server declares for a resource.
      Parameters:
      url - the resource
      Returns:
      the size in bytes, or a negative value if the server did not say

    • deleteWithSidecars

      protected void deleteWithSidecars(File target)
      Deletes a cached map along with its validation and metadata sidecars.
      Parameters:
      target - the cached map