/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 * created at Oct 18, 2008
 */
package org.biojava.nbio.structure.io;

import org.biojava.nbio.structure.PDBStatus;
import org.biojava.nbio.structure.PDBStatus.Status;
import org.biojava.nbio.structure.Structure;
import org.biojava.nbio.structure.StructureException;
import org.biojava.nbio.structure.align.util.UserConfiguration;
import org.biojava.nbio.structure.io.util.FileDownloadUtils;
import org.biojava.nbio.core.util.InputStreamProvider;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.*;

/**
 * Superclass for classes which download and interact with the PDB's FTP server,
 * specifically {@link PDBFileReader} and {@link 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
 *
 */
public abstract class LocalPDBDirectory implements StructureIOFile {

	private static final Logger logger = LoggerFactory.getLogger(LocalPDBDirectory.class);

	/**
	 * 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
	 */
	public static final String DEFAULT_PDB_FILE_SERVER = "http://ftp.wwpdb.org";
	public static final String PDB_FILE_SERVER_PROPERTY = "PDB.FILE.SERVER";

	/**
	 * Behaviors for when an obsolete structure is requested.
	 * @author Spencer Bliven
	 * @see LocalPDBDirectory#setObsoleteBehavior(ObsoleteBehavior)
	 */
	public static enum ObsoleteBehavior {
		/** Fetch the most recent version of the PDB entry. */
		FETCH_CURRENT,
		/** Fetch the obsolete entry from the PDB archives. */
		FETCH_OBSOLETE,
		/** Throw a StructureException for obsolete entries.*/
		THROW_EXCEPTION;

		public static final ObsoleteBehavior DEFAULT=THROW_EXCEPTION;
	}

	/**
	 * Controls when the class should fetch files from the ftp server
	 * @author Spencer Bliven
	 *
	 */
	public static enum FetchBehavior {
		/** Never fetch from the server; Throw errors for missing files */
		LOCAL_ONLY,
		/** Fetch missing files from the server. Don't check for outdated files */
		FETCH_FILES,
		/**
		 * Fetch missing files from the server, also fetch if file present but older than the
		 * server file.
		 * This requires always querying the server for the last modified time of the file, thus
		 * it adds an overhead to getting files from cache.
		 */
		FETCH_IF_OUTDATED,
		/**
		 * Fetch missing files from the server.
		 * Also force the download of files older than {@value #LAST_REMEDIATION_DATE_STRING}.
		 */
		FETCH_REMEDIATED,
		/** For every file, force downloading from the server */
		FORCE_DOWNLOAD;

		public static final FetchBehavior DEFAULT = FETCH_REMEDIATED;
	}

	/**
	 * Date of the latest PDB file remediation
	 */
	public static final long LAST_REMEDIATION_DATE ;
	private static final String LAST_REMEDIATION_DATE_STRING = "2011/07/12";

	static {

		SimpleDateFormat formatter = new SimpleDateFormat("yyyy/MM/dd", Locale.US);

		long t = 0;
		try {
			Date d = formatter.parse(LAST_REMEDIATION_DATE_STRING);
			t = d.getTime();
		} catch (ParseException e){
			logger.error("Unexpected error! could not parse LAST_REMEDIATION_DATE: "+e.getMessage());
		}
		LAST_REMEDIATION_DATE = t;
	}

	protected static final String lineSplit = System.getProperty("file.separator");

	private File path;
	private List<String> extensions;

	/**
	 * The 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
	 */
	private String serverName;

	private FileParsingParameters params;

	private ObsoleteBehavior obsoleteBehavior;
	private FetchBehavior fetchBehavior;


	// Cache results of get*DirPath()
	private String splitDirURL; // path on the server, starting with a slash and ending before the 2-char split directories
	private String obsoleteDirURL;
	private File splitDirPath; // path to the directory before the 2-char split
	private File obsoleteDirPath;

	/**
	 * Subclasses should provide default and single-string constructors.
	 * They should use {@link #addExtension(String)} to add one or more extensions.
	 *
	 * <p>If path is null, initialize using the system property/environment variable
	 * {@link UserConfiguration#PDB_DIR}.
	 * @param path Path to the PDB file directory
	 */
	public LocalPDBDirectory(String path) {
		extensions    = new ArrayList<String>();

		params = new FileParsingParameters();

		if( path == null) {
			UserConfiguration config = new UserConfiguration();
			path = config.getPdbFilePath();
			logger.debug("Initialising from system property/environment variable to path: {}", path.toString());
		} else {
			path = FileDownloadUtils.expandUserHome(path);
			logger.debug("Initialising with path {}", path.toString());
		}
		this.path = new File(path);

		this.serverName = getServerName();

		// Initialize splitDirURL,obsoleteDirURL,splitDirPath,obsoleteDirPath
		initPaths();

		fetchBehavior = FetchBehavior.DEFAULT;
		obsoleteBehavior = ObsoleteBehavior.DEFAULT;
	}

	public LocalPDBDirectory() {
		this(null);
	}

	/**
	 * Sets the path for the directory where PDB files are read/written
	 */
	public void setPath(String p){
		path = new File(FileDownloadUtils.expandUserHome(p)) ;
		initPaths();
	}

	/**
	 * Returns the path value.
	 * @return a String representing the path value
	 * @see #setPath
	 *
	 */
	public String getPath() {
		return path.toString() ;
	}

	/** define supported file extensions
	 * compressed extensions .Z,.gz do not need to be specified
	 * they are dealt with automatically.
	 */
	@Override
	public void addExtension(String s){
		//System.out.println("add Extension "+s);
		extensions.add(s);
	}

	@Override
	public List<String> getExtensions() {
		return Collections.unmodifiableList(extensions);
	}

	/** clear the supported file extensions
	 *
	 */
	public void clearExtensions(){
		extensions.clear();
	}

	/**
	 * @deprecated Use {@link #getFetchBehavior()}
	 */
	@Deprecated
	public boolean isAutoFetch() {
		return fetchBehavior != FetchBehavior.LOCAL_ONLY;
	}

	/**
	 * @deprecated Use {@link #setFetchBehavior()}
	 */
	@Deprecated
	public void setAutoFetch(boolean autoFetch) {
		logger.warn("LocalPDBDirectory.setAutoFetch() is deprecated, please use LocalPDBDirectory.setFetchBehavior() instead. The option will be removed in upcoming releases");
		if(autoFetch) {
			setFetchBehavior(FetchBehavior.DEFAULT);
		} else {
			setFetchBehavior(FetchBehavior.LOCAL_ONLY);
		}
	}

	@Override
	public void setFileParsingParameters(FileParsingParameters params){
		this.params= params;
	}

	@Override
	public FileParsingParameters getFileParsingParameters(){
		return params;
	}

	/**
	 * <b>[Optional]</b> This method changes the behavior when obsolete entries
	 * are requested. Current behaviors are:
	 * <ul>
	 * <li>{@link ObsoleteBehavior#THROW_EXCEPTION THROW_EXCEPTION}
	 *   Throw a {@link StructureException} (the default)
	 * <li>{@link ObsoleteBehavior#FETCH_OBSOLETE FETCH_OBSOLETE}
	 *   Load the requested ID from the PDB's obsolete repository
	 * <li>{@link ObsoleteBehavior#FETCH_CURRENT FETCH_CURRENT}
	 *   Load the most recent version of the requested structure
	 *
	 * <p>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 {@link #isAutoFetch()} is false. Note that an obsolete entry may still be
	 * returned even this is FETCH_CURRENT if the entry is found locally.
	 *
	 * @param fetchFileEvenIfObsolete Whether to fetch obsolete records
	 * @see #setFetchCurrent(boolean)
	 * @since 4.0.0
	 */
	public void setObsoleteBehavior(ObsoleteBehavior behavior) {
		obsoleteBehavior = behavior;
	}

	/**
	 * 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 {@link #isAutoFetch()} is false.
	 *
	 * <p>For most implementations, the default value is
	 * {@link ObsoleteBehavior#THROW_EXCEPTION THROW_EXCEPTION}.
	 *
	 * @return The ObsoleteBehavior
	 * @since 4.0.0
	 */
	public ObsoleteBehavior getObsoleteBehavior() {
		return obsoleteBehavior;
	}

	/**
	 * Get the behavior for fetching files from the server
	 * @return
	 */
	public FetchBehavior getFetchBehavior() {
		return fetchBehavior;
	}
	/**
	 * Set the behavior for fetching files from the server.
	 * This replaces the {@link #setAutoFetch(boolean)} method with a more
	 * extensive set of options.
	 * @param fetchBehavior
	 */
	public void setFetchBehavior(FetchBehavior fetchBehavior) {
		this.fetchBehavior = fetchBehavior;
	}


	@Override
	public Structure getStructure(String filename) throws IOException
	{
		filename = FileDownloadUtils.expandUserHome(filename);
		File f = new File(filename);
		return getStructure(f);

	}

	public Structure getStructure(URL u) throws IOException{
		InputStreamProvider isp = new InputStreamProvider();
		InputStream inStream = isp.getInputStream(u);
		return getStructure(inStream);
	}

	@Override
	public Structure getStructure(File filename) throws IOException {
		InputStreamProvider isp = new InputStreamProvider();

		InputStream inStream = isp.getInputStream(filename);

		return getStructure(inStream);
	}


	@Override
	public Structure getStructureById(String pdbId) throws IOException {
		InputStream inStream = getInputStream(pdbId);

		return getStructure(inStream);
	}

	/**
	 * Handles the actual parsing of the file into a Structure object.
	 * @param inStream
	 * @return
	 * @throws IOException
	 */
	public abstract Structure getStructure(InputStream inStream) throws IOException;

	/**
	 * Load or download the specified structure and return it as an InputStream
	 * for direct parsing.
	 * @param pdbId
	 * @return
	 * @throws IOException
	 */
	protected InputStream getInputStream(String pdbId) throws IOException{

		if ( pdbId.length() != 4)
			throw new IOException("The provided ID does not look like a PDB ID : " + pdbId);

		// Check existing
		File file = downloadStructure(pdbId);

		if(!file.exists()) {
			throw new IOException("Structure "+pdbId+" not found and unable to download.");
		}

		InputStreamProvider isp = new InputStreamProvider();

		InputStream inputStream = isp.getInputStream(file);

		return inputStream;
	}

	/**
	 * Download a structure, but don't parse it yet or store it in memory.
	 *
	 * Used to pre-fetch large numbers of structures.
	 * @param pdbId
	 * @throws IOException
	 */
	public void prefetchStructure(String pdbId) throws IOException {
		if ( pdbId.length() != 4)
			throw new IOException("The provided ID does not look like a PDB ID : " + pdbId);

		// Check existing
		File file = downloadStructure(pdbId);

		if(!file.exists()) {
			throw new IOException("Structure "+pdbId+" not found and unable to download.");
		}
	}

	/**
	 * Attempts to delete all versions of a structure from the local directory.
	 * @param pdbId
	 * @return True if one or more files were deleted
	 */
	public boolean deleteStructure(String pdbId){
		boolean deleted = false;
		// Force getLocalFile to check in obsolete locations
		ObsoleteBehavior obsolete = getObsoleteBehavior();
		setObsoleteBehavior(ObsoleteBehavior.FETCH_OBSOLETE);

		try {
			File existing = getLocalFile(pdbId);
			while(existing != null) {
				assert(existing.exists()); // should exist unless concurrency problems

				if( getFetchBehavior() == FetchBehavior.LOCAL_ONLY) {
					throw new RuntimeException("Refusing to delete from LOCAL_ONLY directory");
				}

				// delete file
				boolean success = existing.delete();
				if(success) {
					logger.info("Deleting "+existing.getAbsolutePath());
				}
				deleted = deleted || success;

				// delete parent if empty
				File parent = existing.getParentFile();
				if(parent != null) {
					success = parent.delete();
					if(success) {
						logger.info("Deleting "+parent.getAbsolutePath());
					}
				}

				existing = getLocalFile(pdbId);
			}
			return deleted;

		} finally {
			setObsoleteBehavior(obsolete);
		}
	}

	/**
	 * Downloads an MMCIF file from the PDB to the local path
	 * @param pdbId
	 * @return The file, or null if it was unavailable for download
	 * @throws IOException for errors downloading or writing, or if the
	 *  fetchBehavior is {@link FetchBehavior#LOCAL_ONLY}
	 */
	@SuppressWarnings("deprecation") //for isUpdateRemediatedFiles()
	protected File downloadStructure(String pdbId) throws IOException{
		if ( pdbId.length() != 4)
			throw new IOException("The provided ID does not look like a PDB ID : " + pdbId);

		// decide whether download is required
		File existing =  getLocalFile(pdbId);
		switch(fetchBehavior) {
		case LOCAL_ONLY:
			if( existing == null ) {
				throw new IOException(String.format("Structure %s not found in %s "
						+ "and configured not to download.",pdbId,getPath()));
			} else {
				return existing;
			}
		case FETCH_FILES:
			// Use existing if present
			if( existing != null) {
				// Respect deprecated remediation parameter for backwards compatibility
				if(getFileParsingParameters().isUpdateRemediatedFiles()) {
					long lastModified = existing.lastModified();

					if (lastModified < LAST_REMEDIATION_DATE) {
						logger.warn("FileParsingParameters.setUpdateRemediatedFiles() is deprecated, please use LocalPDBDirectory.setFetchBehavior() instead. The option will be removed in upcoming releases");
						// the file is too old, replace with newer version
						logger.warn("Replacing file {} with latest remediated (remediation of {}) file from PDB.",
								existing, LAST_REMEDIATION_DATE_STRING);
						break;
					}
				}

				return existing;
			}
			// existing is null, downloadStructure(String,String,boolean,File) will download it
			break;
		case FETCH_IF_OUTDATED:
			// here existing can be null or not:
			// existing == null : downloadStructure(String,String,boolean,File) will download it
			// existing != null : downloadStructure(String,String,boolean,File) will check its date and download if older
			break;
		case FETCH_REMEDIATED:
			// Use existing if present and recent enough
			if( existing != null) {
				long lastModified = existing.lastModified();

				if (lastModified < LAST_REMEDIATION_DATE) {
					// the file is too old, replace with newer version
					logger.warn("Replacing file {} with latest remediated (remediation of {}) file from PDB.",
							existing, LAST_REMEDIATION_DATE_STRING);
					existing = null;
					break;
				} else {
					return existing;
				}
			}
		case FORCE_DOWNLOAD:
			// discard the existing file to force redownload
			existing = null; // downloadStructure(String,String,boolean,File) will download it
			break;
		}

		// Force the download now
		if(obsoleteBehavior == ObsoleteBehavior.FETCH_CURRENT) {
			String current = PDBStatus.getCurrent(pdbId);

			if(current == null) {
				// either an error or there is not current entry
				current = pdbId;
			}
			return downloadStructure(current, splitDirURL,false, existing);
		} else if(obsoleteBehavior == ObsoleteBehavior.FETCH_OBSOLETE
				&& PDBStatus.getStatus(pdbId) == Status.OBSOLETE) {
			return downloadStructure(pdbId, obsoleteDirURL, true, existing);
		} else {
			return downloadStructure(pdbId, splitDirURL, false, existing);
		}
	}

	/**
	 * Download a file from the ftp server, replacing any existing files if needed
	 * @param pdbId PDB ID
	 * @param pathOnServer Path on the FTP server, e.g. data/structures/divided/pdb
	 * @param obsolete Whether or not file should be saved to the obsolete location locally
	 * @param existingFile if not null and checkServerFileDate is true, the last modified date of the
	 * server file and this file will be compared to decide whether to download or not
	 * @return
	 * @throws IOException
	 */
	private File downloadStructure(String pdbId, String pathOnServer, boolean obsolete, File existingFile)
			throws IOException{

		File dir = getDir(pdbId,obsolete);
		File realFile = new File(dir,getFilename(pdbId));

		String ftp = String.format("%s%s/%s/%s",
				serverName, pathOnServer, pdbId.substring(1,3).toLowerCase(), getFilename(pdbId));

		URL url = new URL(ftp);

		Date serverFileDate = null;
		if (existingFile!=null) {

			serverFileDate = getLastModifiedTime(url);

			if (serverFileDate!=null) {
				if (existingFile.lastModified()>=serverFileDate.getTime()) {
					return existingFile;
				} else {
					// otherwise we go ahead and download, warning about it first
					logger.warn("File {} is outdated, will download new one from PDB (updated on {})",
							existingFile, serverFileDate.toString());
				}
			} else {
				logger.warn("Could not determine if file {} is outdated (could not get timestamp from server). Will force redownload", existingFile);
			}
		}

		logger.info("Fetching " + ftp);
		logger.info("Writing to "+ realFile);



		FileDownloadUtils.downloadFile(url, realFile);

		// Commented out following code used for setting the modified date to the downloaded file - JD 2015-01-15
		// The only reason to have it was in order to get an rsync-like behavior, respecting the timestamps
		// but the issue is that it would make the FETCH_REMEDIATED mode redownload files with timestamps before
		// the remediation.
		//if (serverFileDate==null)
		//	serverFileDate = getLastModifiedTime(url);
		//
		//if (serverFileDate!=null) {
		//	logger.debug("Setting modified time of downloaded file {} to {}",realFile,serverFileDate.toString());
		//	realFile.setLastModified(serverFileDate.getTime());
		//} else {
		//	logger.warn("Unknown modified time of file {}, will set its modified time to now.", ftp);
		//}


		return realFile;
	}

	/**
	 * Get the last modified time of the file in given url by retrieveing the "Last-Modified" header.
	 * Note that this only works for http URLs
	 * @param url
	 * @return the last modified date or null if it couldn't be retrieved (in that case a warning will be logged)
	 */
	private Date getLastModifiedTime(URL url) {

		// see http://stackoverflow.com/questions/2416872/how-do-you-obtain-modified-date-from-a-remote-file-java
		Date date = null;
		try {
			String lastModified = url.openConnection().getHeaderField("Last-Modified");
			logger.debug("Last modified date of server file ({}) is {}",url.toString(),lastModified);


			if (lastModified!=null) {

				try {
					date = new SimpleDateFormat("E, d MMM yyyy HH:mm:ss Z", Locale.ENGLISH).parse(lastModified);
				} catch (ParseException e) {
					logger.warn("Could not parse last modified time from string '{}', no last modified time available for file {}",
							lastModified, url.toString());
					// this will return null
				}

			}
		} catch (IOException e) {
			logger.warn("Problems while retrieving last modified time for file {}", url.toString());
		}
		return date;

	}

	/**
	 * 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.
	 * @param pdbId
	 * @param obsolete Whether the pdbId is obsolete or not
	 * @return File pointing to the directory,
	 */
	protected File getDir(String pdbId, boolean obsolete) {

		File dir = null;

		if (obsolete) {
			// obsolete is always split
			String middle = pdbId.substring(1,3).toLowerCase();
			dir = new File(obsoleteDirPath, middle);
		} else {
			String middle = pdbId.substring(1,3).toLowerCase();
			dir = new File(splitDirPath, middle);
		}


		if (!dir.exists()) {
			boolean success = dir.mkdirs();
			if (!success) logger.error("Could not create mmCIF dir {}",dir.toString());
		}

		return dir;
	}

	/**
	 * Searches for previously downloaded files
	 * @param pdbId
	 * @return A file pointing to the existing file, or null if not found
	 */
	public File getLocalFile(String pdbId) {

		// Search for existing files

		// Search directories:
		// 1) LOCAL_MMCIF_SPLIT_DIR/<middle>/(pdb)?<pdbId>.<ext>
		// 2) LOCAL_MMCIF_ALL_DIR/<middle>/(pdb)?<pdbId>.<ext>
		LinkedList<File> searchdirs = new LinkedList<File>();
		String middle = pdbId.substring(1,3).toLowerCase();

		File splitdir = new File(splitDirPath, middle);
		searchdirs.add(splitdir);
		// Search obsolete files if requested
		if(getObsoleteBehavior() == ObsoleteBehavior.FETCH_OBSOLETE) {
			File obsdir = new File(obsoleteDirPath,middle);
			searchdirs.add(obsdir);
		}

		// valid prefixes before the <pdbId> in the filename
		String[] prefixes = new String[] {"", "pdb"};

		for( File searchdir :searchdirs){
			for( String prefix : prefixes) {
				for(String ex : getExtensions() ){
					File f = new File(searchdir,prefix + pdbId.toLowerCase() + ex) ;
					if ( f.exists()) {
						return f;
					}
				}
			}
		}
		//Not found
		return null;
	}

	protected boolean checkFileExists(String pdbId){
		File path =  getLocalFile(pdbId);
		if ( path != null)
			return true;
		return false;
	}

	/**
	 * 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 {@value #DEFAULT_PDB_FILE_SERVER} or the one
	 * read from system property {@value #PDB_FILE_SERVER_PROPERTY}
	 *
	 * @return the server name including the leading protocol string
	 */
	public static String getServerName() {
		String name = System.getProperty(PDB_FILE_SERVER_PROPERTY);

		if ( name == null || name.trim().isEmpty()) {
			name = DEFAULT_PDB_FILE_SERVER;
			logger.debug("Using default PDB file server {}",name);
		} else {
			if (!name.startsWith("http://") && !name.startsWith("ftp://")) {
				logger.warn("Server name {} read from system property {} does not have a leading protocol string. Adding http:// to it", name, PDB_FILE_SERVER_PROPERTY);
				name = "http://"+name;
			}
			logger.info("Using PDB file server {} read from system property {}", name, PDB_FILE_SERVER_PROPERTY);
		}
		return name;
	}

	/**
	 * Should be called whenever any of the path variables change.
	 * Thus, if {@link getSplitDirPath()} or {@link getObsoleteDirPath()}
	 * depend on anything, they should call this function when that thing
	 * changes (possibly including at the end of the constructor).
	 */
	protected void initPaths() {
		// Hand-rolled String.join(), for java 6
		String[] split = getSplitDirPath();
		String[] obsolete = getObsoleteDirPath();

		//URLs are joined with '/'
		StringBuilder splitURL = new StringBuilder("/pub/pdb");
		for(int i=0;i<split.length;i++) {
			splitURL.append("/");
			splitURL.append(split[i]);
		}
		StringBuilder obsoleteURL = new StringBuilder("/pub/pdb");
		for(int i=0;i<obsolete.length;i++) {
			obsoleteURL.append("/");
			obsoleteURL.append(obsolete[i]);
		}

		splitDirURL = splitURL.toString();
		obsoleteDirURL = obsoleteURL.toString();


		//Files join themselves iteratively
		splitDirPath = path;
		for(int i=0;i<split.length;i++) {
			splitDirPath = new File(splitDirPath,split[i]);
		}
		obsoleteDirPath = path;
		for(int i=0;i<obsolete.length;i++) {
			obsoleteDirPath = new File(obsoleteDirPath,obsolete[i]);
		}
	}

	/**
	 * Converts a PDB ID into a filename with the proper extension
	 * @param pdbId
	 * @return The filename, e.g. "4hhb.pdb.gz"
	 */
	protected abstract String getFilename(String pdbId);

	/**
	 * 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.
	 * @return A list of directories, relative to the /pub/pdb directory on the server
	 */
	protected abstract String[] getSplitDirPath();
	/**
	 * 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.
	 * @return A list of directories, relative to the /pub/pdb directory on the server
	 */
	protected abstract String[] getObsoleteDirPath();
}
