//==============================================================================
// DiskCacheFile.java
//------------------------------------------------------------------------------

package tribble.io;


// System imports

import java.io.File;
import java.io.IOException;

import java.lang.Exception;
import java.lang.Integer;
import java.lang.NumberFormatException;
import java.lang.String;
import java.lang.StringBuffer;

import java.text.ParseException;
import java.text.SimpleDateFormat;

import java.util.Date;
import java.util.HashMap;
import java.util.SimpleTimeZone;
import java.util.TimeZone;


// Local imports

// (None)


/*******************************************************************************
* Disk cached document file.
*
* <!------------------------------------------------------------------------ -->
* <p>
* <b> Notes </b>
*
* <p>
* The contents of this document file information object are written to the
* cached directory control file, one line per document file.  The format of the
* information is:
* <pre>
*    filename sep created sep access sep expiry sep sep sep sep docID nl
* </pre>
*
* Which is composed of the following fields:
* <dl>
*  <dt> <tt>sep</tt>
*   <dd>
*    A single separator character (<tt>'|'</tt>), used to delimit the fields in
*    the text line entry.
*
*  <dt> <tt>filename</tt>
*   <dd>
*    The name of the filename in the local cache directory.  This name must not
*    contain any spaces.
*
*  <dt> <tt>created</tt>
*   <dd>
*    The date and time that this document file was created within the cache
*    directory, in the format <tt>YYYYMMDDhhmmss</tt>.
*
*  <dt> <tt>accessed</tt>
*   <dd>
*    The date and time that this document file was last accessed, in the format
*    <tt>YYYYMMDDhhmmss</tt>.
*
*  <dt> <tt>expiry</tt>
*   <dd>
*    The number of days past its last access time that this document file
*    expires, as an unsigned integer.
*
*  <dt> <tt>nl</tt>
*   <dd>
*    A single newline, to terminate the text line entry.
* </dl>
*
* @version	$Revision: 1.1 $ $Date: 2002/06/06 04:10:16 $
* @since	2002-06-04
* @author
*	David R. Tribble,
*	<a href="mailto:david@tribble.com">david@tribble.com</a>
*	<br>
*	Copyright ©2002 by David R. Tribble, all rights reserved.
*
* @see	DiskCacheManager
*/

public class DiskCacheFile
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/io/DiskCacheFile.java $Revision: 1.1 $ $Date: 2002/06/06 04:10:16 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Private constants

    /** Default timezone (UTC, GMT, Zulu). */
    private static final TimeZone	UTC_TZ =
					    new SimpleTimeZone(0, "");

    /** Date/time format specification. */
    private static final String		DATE_FMT =
					    "yyyyMMddHHmmss";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Private static variables

    /** Common date formatter. */
    private static final SimpleDateFormat	s_sdf;


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Static class initializers

    static
    {
        s_sdf = new SimpleDateFormat(DATE_FMT);
        s_sdf.setTimeZone(UTC_TZ);
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected variables

    /** Local directory cache manager that owns (manages) this document file. */
    protected DiskCacheManager	m_mgr;

    /** Document-ID of this document file. */
    protected String		m_docId;

    /** Local cached filename for this document file. */
    protected File		m_fname;

    /** Creation date for this document file. */
    protected Date		m_createTime;

    /** Last access date for this document file. */
    protected Date		m_accessTime;

    /** Days past the last access date that this document file expires. */
    protected int		m_expiryDays =
				    DiskCacheManager.DFL_EXPIRY_DAYS;


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Package private static methods

    /***************************************************************************
    * Reconstruct a document file information object from a control file entry
    * line.
    *
    * @param	line
    * A cache index file entry line, containing information about a document
    * file.
    *
    * @param	dir
    * The cache directory name where the cached file resides.
    *
    * @throws	IOException
    * Thrown if <tt>line</tt> is malformed.
    *
    * @since	1.1, 2002-06-05
    *
    * @see	#toEntryLine
    */

    static DiskCacheFile fromEntryLine(String line, File dir)
        throws IOException
    {
        DiskCacheFile	f;

        try
        {
            String	ent;
            String	fld;
            int		i;

            // Create a new cache document file
            f = new DiskCacheFile();

            // Reconstruct the cache document file info from the index entry
            ent = line;

            // Format: <fname b created b access b expiry b b b b docID>

            // Field: <filename>
            i = ent.indexOf(DiskCacheManager.ENTRY_SEP);
            if (i < 0)
                throw new NumberFormatException("filename");
            f.m_fname = new File(dir, ent.substring(0, i));
            ent = ent.substring(i+1);

            // Field: <created>
            i = ent.indexOf(DiskCacheManager.ENTRY_SEP);
            if (i < 0)
                throw new NumberFormatException("createTime");
            f.m_createTime = fromIso8601(ent.substring(0, i));
            ent = ent.substring(i+1);

            // Field: <access>
            i = ent.indexOf(DiskCacheManager.ENTRY_SEP);
            if (i < 0)
                throw new NumberFormatException("accessTime");
            f.m_accessTime = fromIso8601(ent.substring(0, i));
            ent = ent.substring(i+1);

            // Field: <lifetime>
            i = ent.indexOf(DiskCacheManager.ENTRY_SEP);
            if (i < 0)
                throw new NumberFormatException("lifeTime");
            fld = ent.substring(0, i);
            f.m_expiryDays = Integer.parseInt(fld);
            ent = ent.substring(i+1);

            // Skip this field (for future use)
            i = ent.indexOf(DiskCacheManager.ENTRY_SEP);
            if (i < 0)
                throw new NumberFormatException("future-1");
            ent = ent.substring(i+1);

            // Skip this field (for future use)
            i = ent.indexOf(DiskCacheManager.ENTRY_SEP);
            if (i < 0)
                throw new NumberFormatException("future-2");
            ent = ent.substring(i+1);

            // Skip this field (for future use)
            i = ent.indexOf(DiskCacheManager.ENTRY_SEP);
            if (i < 0)
                throw new NumberFormatException("future-3");
            ent = ent.substring(i+1);

            // Field: <docID>
            if (ent.length() == 0)
                throw new NumberFormatException("docID");
            f.m_docId = ent;
        }
        catch (NumberFormatException ex)
        {
            // Malformed cache index entry
            throw new IOException("Malformed cache index entry: ["
                + line + "]");
        }

        // Done
        return (f);
    }


    /***************************************************************************
    * Convert a date into an ISO-8601 formatted text string.
    *
    * @param	when
    * A date to convert.
    *
    * @return
    * A text string in ISO-8601 format, <tt>"YYYYMMDDhhmmss"</tt>.  The time
    * will be relative to the UTC timezone.
    *
    * @since	1.1, 2002-06-05
    *
    * @see	#fromIso8601
    */

    static String toIso8601(Date when)
    {
        String	s;

        // Format the date as an ISO-8601 string
        s = s_sdf.format(when);
        return (s);
    }


    /***************************************************************************
    * Convert a text string containing a date in ISO-8601 format into a date.
    *
    * @param	s
    * A text string in ISO-8601 format, <tt>"YYYYMMDDhhmmss"</tt>.  The time is
    * assumed to be relative to the UTC timezone.
    *
    * @return
    * A date value.
    *
    * @since	1.1, 2002-06-05
    *
    * @see	#toIso8601
    */

    static Date fromIso8601(String s)
    {
        try
        {
            Date	when;

            // Parse the date as an ISO-8601 string
            when = s_sdf.parse(s);
            return (when);
        }
        catch (ParseException ex)
        {
            // Conversion error
            return (null);
        }
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected constructors

    /***************************************************************************
    * Constructor.
    *
    * @param	docId
    * The document-ID to associate with this cached document file.
    *
    * @param	fname
    * The name of the file residing in the local cache directory associated with
    * this cached document file.
    *
    * @param	mgr
    * The cache directory manager that owns (manages) this cached document file.
    *
    * @since	1.1, 2002-06-04
    *
    * @see	DiskCacheManager#createFile
    */

    protected DiskCacheFile(String docId, File fname, DiskCacheManager mgr)
    {
        // Initialize this cached document file
        m_docId = docId;
        m_fname = fname;
        m_mgr =   mgr;
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected methods

    /***************************************************************************
    * Determine if this document file has expired or not.
    *
    * @param	now
    * The current date.
    *
    * @return
    * True if this document file has expired, otherwise false.
    *
    * @since	1.1, 2002-06-04
    *
    * @see	DiskCacheManager#setExpiryDays
    * @see	DiskCacheManager#removeAllExpiredFiles
    * @see	DiskCacheManager#removeExpiredEntries
    */

    protected boolean hasExpired(Date now)
    {
        long	msec;

        // Compute the expiration date of this document file
        msec = m_expiryDays * (24L*3600*1000);
        msec += m_accessTime.getTime();

        // Compare the expiration date to the current date
        return (now.getTime() >= msec);
    }


    /***************************************************************************
    * Construct a control file entry line out of this cached document file
    * information object.
    *
    * @return
    * A cache index file entry line, containing information about this document
    * file.
    *
    * @since	1.1, 2002-06-04
    *
    * @see	#fromEntryLine
    */

    protected String toEntryLine()
    {
        StringBuffer	buf;

        // Format: <fname b created b access b expiry b - b - b - b docID>
        buf = new StringBuffer(80);

        buf.append(m_fname.getName());
        buf.append(DiskCacheManager.ENTRY_SEP);

        buf.append(toIso8601(m_createTime));
        buf.append(DiskCacheManager.ENTRY_SEP);

        buf.append(toIso8601(m_accessTime));
        buf.append(DiskCacheManager.ENTRY_SEP);

        buf.append(m_expiryDays);
        buf.append(DiskCacheManager.ENTRY_SEP);

        buf.append("");				// For future use
        buf.append(DiskCacheManager.ENTRY_SEP);

        buf.append("");				// For future use
        buf.append(DiskCacheManager.ENTRY_SEP);

        buf.append("");				// For future use
        buf.append(DiskCacheManager.ENTRY_SEP);

        buf.append(m_docId);

        return (buf.toString());
    }


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Private constructors

    /***************************************************************************
    * Default constructor.
    * This is private to prevent empty instantiations.
    *
    * @since	1.1, 2002-06-04
    */

    private DiskCacheFile()
    {
        // Do nothing
    }
}

// End DiskCacheFile.java