CodeSnip Old Code (SVN)

{
 * DB.UDataPool.pas
 *
 * Implements a generic data pool object used to store various database objects.
 *
 * $Rev$
 * $Date$
 *
 * ***** BEGIN LICENSE BLOCK *****
 *
 * Version: MPL 1.1
 *
 * The contents of this file are subject to the Mozilla Public License Version
 * 1.1 (the "License"); you may not use this file except in compliance with the
 * License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
 * the specific language governing rights and limitations under the License.
 *
 * The Original Code is DB.UDataPool.pas
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2010 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributor(s)
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
}


unit DB.UDataPool;

interface

uses
  // Delphi
  Generics.Collections,
  // Project
  DB.UCookies, DB.UDataItem, DB.UObjectDestructionMgr,
  UBaseObjects, UExceptions;

type

  {
  EDBDataPoolError:
    Class of exception raised by TDBDataPool methods.
  }
  EDBDataPoolError = class(EBug);


  {
  TDBDataPool:
    Generic object that implements a pool of data item objects. Designed for use
    in storing database objects that are identified by a cookie and cannot be
    freed by users of the objects. Objects placed in the pool can only be freed
    when the pool permits it.
  }
  TDBDataPool<T: TDBDataItem> = class(TOwnedConditionalFreeObject)
  strict private
    fFreeController: TObjectDestructionMgr; // Controls freeing of data items
    fMap: TDictionary<TDBCookie,T>;   // Maps cookies to data item object
    function GetItem(const Cookie: TDBCookie): T;
      {Gets reference to object associated with a cookie in the pool.
        @param Cookie [in] Cookie to search for.
        @return Required object reference.
        @except Raises EDBDataPoolError if cookie is not in pool.
      }
    function GetCookies: TEnumerable<TDBCookie>;
      {Gets reference to cookies collection from pool. Collection will be freed
      when pool object is freed.
        @return Required collection.
      }
  public
    constructor Create(const Capacity: Integer = 0);
      {Constructor. Optionally sets pool's capacity.
        @param Capacity [in] Optional pool capacity.
      }
    destructor Destroy; override;
      {Destructor. Clears pools and frees contained objects.
      }
    function IsInPool(const Cookie: TDBCookie): Boolean;
      {Checks if a cookie exists in pool.
        @param Cookie [in] Cookie to check.
        @return True if cookie exists, False otherwise.
      }
    procedure Add(const Obj: T);
      {Adds object to pool.
        @param Obj [in] Object to add to pool.
        @except Raises EDBDataPoolError if object's cookie is already in pool.
      }
    procedure Remove(const Cookie: TDBCookie);
      {Removes object with given cookie from pool and frees it.
        @param Cookie of object to be removed.
        @except Raises EDBDataPoolError if Cookie not found.
      }
    procedure Clear;
      {Clears pool and frees contained objects.
      }
    function Count: Integer;
      {Gets number of objects in pool.
        @return Required number of objects.
      }
    function GetEnumerator: TEnumerator<T>;
      {Gets enumerator for the pool. Enumerates values. Cookies are not
      enumerated but can be retrieved from value's Cookie property.
        @return Required enumerator.
      }
    property Items[const Cookie: TDBCookie]: T read GetItem; default;
      {Gets object associated with a cookie from pool}
    property Cookies: TEnumerable<TDBCookie> read GetCookies;
      {Gets an enumerable collection of cookies from pool}
  end;

resourcestring  // must be declared in interface: used in parameterised type
  // TDBDataPool<T> Error messages
  sObjectPoolCookieExists = 'Object with same cookie already exists';
  sObjectPoolCookieMissing = 'No object with given cookie found';
  sObjectPoolCookieIsNul = 'Attempt to add data item with nul cookie to pool';


implementation


uses
  // Delphi
  Generics.Defaults;


{ TDBDataPool<T> }

procedure TDBDataPool<T>.Add(const Obj: T);
  {Adds object to pool.
    @param Obj [in] Object to add to pool.
    @except Raises EDBDataPoolError if object's cookie is already in pool.
  }
begin
  if Obj.Cookie.IsNul then
    raise EDBDataPoolError.Create(sObjectPoolCookieIsNul);
  if IsInPool(Obj.Cookie) then
    raise EDBDataPoolError.Create(sObjectPoolCookieExists);
  fMap.Add(Obj.Cookie, Obj);
  fFreeController.HookController(Obj, True);
end;

procedure TDBDataPool<T>.Clear;
var
  Value: T;
begin
  fFreeController.AllowDestroyAll;
  try
    for Value in fMap.Values do
      Value.Free;
  finally
    fFreeController.AllowDestroyNone;
  end;
  fMap.Clear;
end;

function TDBDataPool<T>.Count: Integer;
begin
  Result := fMap.Count;
end;

constructor TDBDataPool<T>.Create(const Capacity: Integer);
begin
  inherited Create;
  fMap := TDictionary<TDBCookie, T>.Create(
    Capacity,
    TEqualityComparer<TDBCookie>.Construct(
      // equality test
      function(const Left, Right: TDBCookie): Boolean
      begin
        Result := Left = Right;
      end,
      // hash
      function(const Value: TDBCookie): Integer
      begin
        Result := Value.Hash;
      end
    )
  );
  fFreeController := TObjectDestructionMgr.Create;
  fFreeController.AllowDestroyNone;
end;

destructor TDBDataPool<T>.Destroy;
begin
  Clear;
  fMap.Free;
  fFreeController.Free;
  inherited;
end;

function TDBDataPool<T>.GetCookies: TEnumerable<TDBCookie>;
begin
  Result := fMap.Keys;
end;

function TDBDataPool<T>.GetEnumerator: TEnumerator<T>;
begin
  Result := TDictionary<TDBCookie,T>.TValueEnumerator.Create(fMap);
end;

function TDBDataPool<T>.GetItem(const Cookie: TDBCookie): T;
begin
  if not fMap.TryGetValue(Cookie, Result) then
    raise EDBDataPoolError.Create(sObjectPoolCookieMissing);
end;

function TDBDataPool<T>.IsInPool(const Cookie: TDBCookie): Boolean;
begin
  Result := fMap.ContainsKey(Cookie);
end;

procedure TDBDataPool<T>.Remove(const Cookie: TDBCookie);
var
  Obj: T;
begin
  Obj := GetItem(Cookie);
  fMap.Remove(Cookie);
  fFreeController.AllowDestroyCookie(Obj.Cookie);
  try
    Obj.Free;
  finally
    fFreeController.AllowDestroyNone;
  end;
end;

end.