CodeSnip Old Code (SVN)

{
 * This Source Code Form is subject to the terms of the Mozilla Public License,
 * v. 2.0. If a copy of the MPL was not distributed with this file, You can
 * obtain one at http://mozilla.org/MPL/2.0/
 *
 * Copyright (C) 2005-2013, Peter Johnson (www.delphidabbler.com).
 *
 * $Rev$
 * $Date$
 *
 * Object used to manage database updates from web.
}


unit UDBUpdateMgr;


interface


uses
  // Delphi
  SysUtils,
  // Project
  UDOSDateTime, UEncodings, Web.UDBDownloadMgr;



type
  ///  <summary>Manages the process of checking update availability and perform
  ///  updates of the local Code Snippets Database from the online version.
  ///  </summary>
  TDBUpdateMgr = class(TObject)
  public
    type
      ///  <summary>
      ///  <para>Enumeration of possible results of a database update request.
      ///  </para>
      ///  <para>- urUpdated - local database was updated</para>
      ///  <para>- urNoUpdate - no update available: local database up to date.
      ///  </para>
      ///  <para>- urCancelled - user cancelled request.</para>
      ///  <para>- urError - an error occurred.</para>
      ///  </summary>
      TUpdateResult = (urUpdated, urNoUpdate, urCancelled, urError);
    type
      ///  <summary>
      ///  <para>Enumeration of possible result when querying if a database
      ///  updated is available.</para>
      ///  <para>- upUpToDate - local database is up to date.</para>
      ///  <para>- uqUpdateAvailable - a database update is available.</para>
      ///  <para>- uqError - an error occurred during the request.</para>
      ///  </summary>
      TUpdateQueryResult = (uqUpToDate, uqUpdateAvailable, uqError);
    type
      ///  <summary>
      ///  <para>Enumeration of different possible states of database update
      ///  manager during an update request.</para>
      ///  <para>-usLogon - logging on to update web service.</para>
      ///  <para>-usCheckForUpdates - checking for availability of update.
      ///  </para>
      ///  <para>-usDownloadStart - starting to download online database.</para>
      ///  <para>-usDownloadEnd - finished downloading online database.</para>
      ///  <para>-usUpdating - updating local database.</para>
      ///  <para>-usNoUpdate - no update available.</para>
      ///  <para>-usLogOff - logging off web service.</para>
      ///  <para>-usCompleted - completed update process.</para>
      ///  <para>-usCancelled - update process was cancelled.</para>
      ///  </summary>
      TStatus = (
        usLogOn, usCheckForUpdates, usDownloadStart, usDownloadEnd, usUpdating,
        usNoUpdate, usLogOff, usCompleted, usCancelled
      );
    type
      ///  <summary>Type of event triggered when status changes during an update
      ///  request.</summary>
      ///  <param name="Sender">TObject [in] Object that triggered event.
      ///  </param>
      ///  <param name="Status">TDBUpdateMgr.TStatus [in] Current status.
      ///  </param>
      ///  <param name="Cancel">Boolean [in,out] Flag that event handler can set
      ///  True to abort the update.</param>
      TStatusEvent = procedure(Sender: TObject; Status: TStatus;
        var Cancel: Boolean) of object;
    type
      ///  <summary>Type of event triggered to report progress when downloading
      ///  the online database.</summary>.
      ///  <param name="Sender">TObject [in] Object that triggered event.
      ///  </param>
      ///  <param name="BytesHandled">Int64 [in] Number of bytes downloaded so
      ///  far.</param>
      ///  <param name="TotalBytes">Int64 [in] Total number of bytes to be
      ///  downloaded.</param>
      ///  <param name="Cancel">Boolean [in,out] Flag that event handler can set
      ///  True to abort the update.</param>
      TDownloadEvent = procedure(Sender: TObject; const BytesHandled,
        TotalBytes: Int64; var Cancel: Boolean) of object;
    type
      ///  <summary>Type of event triggered to report progress when updating
      ///  local database files.</summary>
      ///  <param name="Sender">TObject [in] Object that triggered event.
      ///  </param>
      ///  <param name="Progress">Bytes [in] Pecentage progress to date.</param>
      ///  <param name="Cancel">Boolean [in,out] Flag that event handler can set
      ///  True to abort the update.</param>
      TProgressEvent = procedure(Sender: TObject; const Progress: Byte;
        var Cancel: Boolean) of object;
  strict private
    var
      ///  <summary>Flag that indicates if an update request was cancelled.
      ///  </summary>
      fCancelled: Boolean;
      ///  <summary>Object that interacts with database download web service.
      ///  </summary>
      fDownloadMgr: TDBDownloadMgr;
      ///  <summary>Directory when the local database files are stored.
      ///  </summary>
      fLocalDir: string;
      ///  <summary>Value of LongError property.</summary>
      fLongError: string;
      ///  <summary>Value of ShortError property.</summary>
      fShortError: string;
      ///  <summary>Event handler for OnStatus event.</summary>
      fOnStatus: TStatusEvent;
      ///  <summary>Event handler for OnDownloadProgress event.</summary>
      fOnDownloadProgress: TDownloadEvent;
      ///  <summary>Event handler for OnFileUpdateProgress event.</summary>
      fOnFileUpdateProgress: TProgressEvent;
      ///  <summary>Information specific to the code using this object.
      ///  </summary>
      fCallerInfo: string;

    ///  <summary>Handles database download manager's OnProgress event.
    ///  </summary>
    ///  <param name="Sender">TObject [in] Object that triggered event.</param>
    ///  <param name="BytesToDate">Int64 [in] Number of bytes downloaded so
    ///  far.</param>
    ///  <param name="ExpectedBytes">Int64 [in] Total number of bytes to be
    ///  downloaded.</param>
    procedure DownloadProgressHandler(Sender: TObject; const BytesToDate,
      ExpectedBytes: Int64);

    ///  <summary>Handles file updater's OnProgress event.</summary>
    ///  <param name="Sender">TObject [in] Object that triggered event.</param>
    ///  <param name="FilesHandled">Cardinal [in] Number of files updated to
    ///  date.</param>
    ///  <param name="TotalFiles">Cardinal [in] Total number of files to be
    ///  updated.</param>
    procedure FileUpdateProgressHandler(Sender: TObject; const AFilesHandled,
      ATotalFiles: Cardinal);

    ///  <summary>Returns the number of files in the local copy of the Code
    ///  Snippets database.</summary>
    function LocalFileCount: Integer;

    ///  <summary>Returns an object that encapsulate the last update date of
    ///  the newest file in the local copy of the Code Snippets database.
    ///  </summary>
    function NewestLocalFileDate: IDOSDateTime;

    ///  <summary>Checks if the local Code Snippets database files need to be
    ///  updated.</summary>
    ///  <returns>Boolean. True if an update is required or False if not or if
    ///  process was cancelled.</returns>
    ///  <remarks>Compares date of newest local database file with last update
    ///  date of online database.</remarks>
    function UpdateNeeded: Boolean;

    ///  <summary>Downloads database and updates local files.</summary>
    ///  <returns>Boolean. True if download and update succeeded or False if
    ///  the process was cancelled.</returns>
    function PerformUpdate: Boolean;

    ///  <summary>Logs on to web server.</summary>
    ///  <returns>Boolean. True if log-on succeeded or False if the process was
    ///  cancelled.</returns>
    function LogOn: Boolean;

    ///  <summary>Logs off web server.</summary>
    procedure LogOff;

    ///  <summary>Downloads a copy of the online database.</summary>
    ///  <param name="Data">TEncodedData [out] Receives data containing the
    ///  downloaded database.</param>
    ///  <returns>Boolean. True on success or False if process is cancelled.
    ///  </returns>
    function DownloadDatabase(out Data: TEncodedData): Boolean;

    ///  <summary>Updates the files in the local database from the downloaded
    ///  data.</summary>
    ///  <param name="Data">TEncodedData [in] Data containing downloaded
    ///  database.</param>
    ///  <returns>Boolean. True on success or False if process is cancelled.
    ///  </returns>
    function UpdateLocalDatabase(const Data: TEncodedData): Boolean;

    ///  <summary>Handles various types of known exception, recording their
    ///  messages.</summary>
    ///  <param name="E">Exception [in] Exception to be handled.</param>
    ///  <returns>True if exception was handled or False otherwise.</returns>
    ///  <remarks>Supported exception messages are made available via the
    ///  ShortError and LongError properties.</remarks>
    function HandleException(const E: Exception): Boolean;

  strict protected
    ///  <summary>Notifies a change in the status of an update request by
    ///  triggering the OnStatus event.</summary>
    ///  <param name="Status">TDBUpdateMgr.TStatus [in] New status.</param>
    ///  <returns>Boolean. True if event handler did not set Cancelled flag,
    ///  False otherwise.</returns>
    function NotifyStatus(Status: TStatus): Boolean; virtual;

  public

    ///  <summary>Constructs and initialises a new object instance.</summary>
    ///  <param name="LocalDir">string [in] Directory that contains the local
    ///  copy of the Code Snippets database.</param>
    ///  <param name="CallerInfo">string [in] Information about calling code.
    ///  </param>
    constructor Create(const LocalDir, CallerInfo: string);

    ///  <summary>Destroys object instance.</summary>
    destructor Destroy; override;

    ///  <summary>Performs a database update.</summary>
    ///  <returns>TDBUpdateMgr.TUpdateResult. Value that indicates if database
    ///  was updated, if process was cancelled or if there has been an error.
    ///  </returns>
    function Execute: TUpdateResult;

    ///  <summary>Queries whether updates to the local database are available.
    ///  </summary>
    ///  <returns>TDBUpdateMgr.TUpdateQueryResult. Value indicating whether a
    ///  update is available or not of if and error occured with the query.
    ///  </returns>
    function CheckForUpdates: TUpdateQueryResult;

    ///  <summary>Full description of last update error.</summary>
    property LongError: string read fLongError;

    ///  <summary>Abbreviated description of last update error.</summary>
    property ShortError: string read fShortError;

    ///  <summary>Event triggered when the status of an update request changes.
    ///  </summary>
    property OnStatus: TStatusEvent read fOnStatus write fOnStatus;

    ///  <summary>Event triggered to report progress when downloading a copy of
    ///  the online database.</summary>
    property OnDownloadProgress: TDownloadEvent
      read fOnDownloadProgress write fOnDownloadProgress;

    ///  <summary>Event triggered to report progress when updating local
    ///  database files.</summary>
    property OnFileUpdateProgress: TProgressEvent
      read fOnFileUpdateProgress write fOnFileUpdateProgress;
  end;


implementation


uses
  // Delphi
  Classes, Math,
  // Project
  IntfCommon, UConsts, UFileUpdater, UUtils, UExceptions;


resourcestring
  // Error messages
  sGeneralUpdateError = 'Update Error';
  sChecksumShortError = 'Corrupt File Error';
  sChecksumLongError = '%s'
    + EOL2
    + 'This is probably caused by an internet transmisson error. Please try '
    + 'downloading again. If the problem persists please report it.';


{ TDBUpdateMgr }

function TDBUpdateMgr.CheckForUpdates: TUpdateQueryResult;
begin
  try
    LogOn;
    if UpdateNeeded then
      Result := uqUpdateAvailable
    else
      Result := uqUpToDate;
    LogOff;
  except
    on E: Exception do
    begin
      Result := uqError;
      if not HandleException(E) then
        raise;
    end;
  end;
end;

constructor TDBUpdateMgr.Create(const LocalDir, CallerInfo: string);
begin
  inherited Create;
  // Create download manager to download from remote web server
  fDownloadMgr := TDBDownloadMgr.Create;
  fDownloadMgr.OnProgress := DownloadProgressHandler;
  fCallerInfo := CallerInfo;
  fLocalDir := LocalDir;
  EnsureFolders(fLocalDir);
end;

destructor TDBUpdateMgr.Destroy;
begin
  fDownloadMgr.Free;
  inherited;
end;

function TDBUpdateMgr.DownloadDatabase(out Data: TEncodedData): Boolean;
begin
  Result := False;
  if not NotifyStatus(usDownloadStart) then
    Exit;
  Data := fDownloadMgr.GetDatabase(True);
  if not NotifyStatus(usDownloadEnd) then
    Exit;
  Result := not fCancelled;
end;

procedure TDBUpdateMgr.DownloadProgresshandler(Sender: TObject;
  const BytesToDate, ExpectedBytes: Int64);
begin
  if Assigned(fOnDownloadProgress) then
    fOnDownloadProgress(Self, BytesToDate, ExpectedBytes, fCancelled);
end;

function TDBUpdateMgr.Execute: TUpdateResult;
begin
  // Assume user cancelled
  Result := urCancelled;
  try
    try
      // Log on to web server
      if not LogOn then
        Exit;
      // Check if we need an update
      if UpdateNeeded then
      begin
        if not PerformUpdate then
          Exit;
        Result := urUpdated;
      end
      else
      begin
        if not NotifyStatus(usNoUpdate) then
          Exit;
        Result := urNoUpdate;
      end;
      // Log off web server
      if not NotifyStatus(usLogOff) then
        Exit;
      LogOff;
      if not NotifyStatus(usCompleted) then
        Exit;
    except
      // Handle known exceptions
      on E: Exception do
      begin
        Result := urError;
        if not HandleException(E) then
          raise;
      end;
    end;
  finally
    if fCancelled then
      NotifyStatus(usCancelled);
  end;
end;

procedure TDBUpdateMgr.FileUpdateProgressHandler(Sender: TObject;
  const AFilesHandled, ATotalFiles: Cardinal);
var
  FilesHandled: Cardinal;
  TotalFiles: Cardinal;
  Percent: Byte;
begin
  if not Assigned(fOnFileUpdateProgress) then
    Exit;
  // Ensure TotalFiles > 0 and 0 <= FilesHandled <= TotalFiles
  TotalFiles := Max(1, ATotalFiles);
  FilesHandled := Min(AFilesHandled, ATotalFiles);
  Percent := Round(100 * FilesHandled / TotalFiles);
  fOnFileUpdateProgress(Self, Percent, fCancelled);
end;

function TDBUpdateMgr.HandleException(const E: Exception): Boolean;
begin
  if E is EDBDownloadMgr then
  begin
    // Download manager exceptions provide both long and short error messages
    fLongError := E.Message;
    fShortError := (E as EDBDownloadMgr).ShortMsg;
    Result := True;
  end
  else if E is EFileUpdater then
  begin
    // File updater exception represent checksum errors
    fLongError := Format(sChecksumLongError, [E.Message]);
    fShortError := sChecksumShortError;
    Result := True;
  end
  else if E is ECodeSnip then
  begin
    // General non-bug exceptions
    fLongError := E.Message;
    fShortError := sGeneralUpdateError;
    Result := True;
  end
  else
    // Don't handle any other exception types
    Result := False;
end;

function TDBUpdateMgr.LocalFileCount: Integer;
var
  LocalFiles: TStringList;  // list of files in local database directory
begin
  LocalFiles := TStringList.Create;
  try
    ListFiles(fLocalDir, '*.*', LocalFiles);
    Result := LocalFiles.Count;
  finally
    LocalFiles.Free;
  end;
end;

procedure TDBUpdateMgr.LogOff;
begin
  fDownloadMgr.LogOff;
end;

function TDBUpdateMgr.LogOn: Boolean;
begin
  Result := False;
  if not NotifyStatus(usLogOn) then
    Exit;
  fDownloadMgr.LogOn(fCallerInfo);
  Result := True;
end;

function TDBUpdateMgr.NewestLocalFileDate: IDOSDateTime;
var
  LocalFiles: TStringList;  // list of files in local data directory
  FileName: string;         // name of a file in local data directory
  FileDate: IDOSDateTime;   // DOS date of a file
begin
  Result := TDOSDateTimeFactory.CreateFromDOSTimeStamp(0);
  // Get all files in directory
  LocalFiles := TStringList.Create;
  try
    ListFiles(fLocalDir, '*.*', LocalFiles);
    if LocalFiles.Count > 0 then
    begin
      for FileName in LocalFiles do
      begin
        FileDate  := TDOSDateTimeFactory.CreateFromFile(FileName);
        if Result.CompareTo(FileDate) < 0 then
          (Result as IAssignable).Assign(FileDate);
      end;
    end;
  finally
    LocalFiles.Free;
  end;
end;

function TDBUpdateMgr.NotifyStatus(Status: TStatus): Boolean;
begin
  if Assigned(fOnStatus) then
    fOnStatus(Self, Status, fCancelled);
  Result := not fCancelled;
end;

function TDBUpdateMgr.PerformUpdate: Boolean;
var
  Data: TEncodedData; // stores downloaded data
begin
  Result := False;
  if fCancelled then
    Exit;
  if DownloadDatabase(Data) then
    Result := UpdateLocalDatabase(Data);
end;

function TDBUpdateMgr.UpdateLocalDatabase(const Data: TEncodedData): Boolean;
var
  Updater: TFileUpdater;  // object that performs file updates.
begin
  Result := False;
  if not NotifyStatus(usUpdating) then
    Exit;
  Updater := TFileUpdater.Create(fLocalDir, Data);
  try
    Updater.OnProgress := FileUpdateProgressHandler;
    Updater.Execute;
    Result := True;
  finally
    Updater.Free;
  end;
end;

function TDBUpdateMgr.UpdateNeeded: Boolean;
var
  LastDatabaseUpdate: IDOSDateTime; // date of newest file in remote database
begin
  Result := False;
  if not NotifyStatus(usCheckForUpdates) then
    Exit;
  // first check if file counts match
  Result := fDownloadMgr.FileCount <> LocalFileCount;
  if not Result then
  begin
    // file count OK: compare last update dates
    LastDatabaseUpdate := TDOSDateTimeFactory.CreateFromUnixTimeStamp(
      StrToInt64(fDownloadMgr.LastUpdate)
    );
    Result := LastDatabaseUpdate.CompareTo(NewestLocalFileDate) > 0;
  end;
end;

end.