{
* 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-2012, Peter Johnson (www.delphidabbler.com).
*
* $Rev$
* $Date$
*
* Set of classes that can register and provide instances of appropriate
* protocol handler classes according to a URL's protocol. Also provides base
* class for all protocol implementations.
}
unit UProtocols;
interface
uses
// Delphi
Generics.Collections,
// Project
UBaseObjects, UExceptions;
type
/// <summary>
/// Abstract base class for all URL protocol handler classes.
/// </summary>
TProtocol = class abstract(TObject)
strict private
var
/// <summary>Value of URL property.</summary>
fURL: string;
strict protected
/// <summary>URL specifying a protocol and a resource.</summary>
property URL: string read fURL;
public
/// <summary>Object constructor. Creates protocol handler for given URL's
/// protocol.</summary>
constructor Create(const URL: string);
/// <summary>Checks if this protocol handler handles a given URL's
/// protocol.</summary>
class function SupportsProtocol(const URL: string): Boolean;
virtual; abstract;
/// <summary>Attempts to execute a resource according to its protocol.
/// Descendants must implement.</summary>
function Execute: Boolean; virtual; abstract;
end;
type
/// <summary>
/// Factory class that creates and registers various TProtocol descendant
/// objects that can handle various supported URL protocols.
/// </summary>
TProtocolFactory = class(TNoConstructObject)
strict private
type
/// <summary>Class reference for TProtocol descendant classes.</summary>
TProtocolClass = class of TProtocol;
type
/// <summary>Implements a register of URL protocol handlers that can be
/// instantiated by protocol factory class.</summary>
TProtocolRegistrar = class(TObject)
strict private
var
/// <summary>List of registered TProtocolClass references.</summary>
fRegister: TList<TProtocolClass>;
/// <summary>Getter for Count property.</summary>
function GetCount: Integer;
/// <summary>Getter for indexed Protocols property.</summary>
function GetProtocol(const Idx: Integer): TProtocolClass;
public
/// <summary>Object constructor. Sets up empty register.</summary>
constructor Create;
/// <summary>Object destructor. Tears down object.</summary>
destructor Destroy; override;
/// <summary>Gets instance of the registrar's enumerator.</summary>
function GetEnumerator: TEnumerator<TProtocolClass>;
/// <summary>Registers the given protocol class.</summary>
procedure RegisterProtocol(const ClassRef: TProtocolClass);
/// <summary>Indexed list of registered protocol classes.</summary>
property Protocols[const Idx: Integer]: TProtocolClass
read GetProtocol; default;
/// <summary>Number of registered protocols.</summary>
property Count: Integer read GetCount;
end;
/// <summary>Gets singleton instance of protocol registrar.</summary>
class function Registrar: TProtocolRegistrar;
class var
/// <summary>Protocol registrar singleton.</summary>
fRegistrar: TProtocolRegistrar;
public
/// <summary>Class constructor. Creates registrar singleton.</summary>
class constructor Create;
/// <summary>Class destructor. Frees registrar singleton.</summary>
class destructor Destroy;
/// <summary>Creates an appropriate concrete TProtocol class instance for
/// given URL's protocol.</summary>
/// <remarks>If no handler has been registered for the URL's protocol a nul
/// handler instance is returned.</remarks>
class function CreateHandler(const URL: string): TProtocol;
/// <summary>Registers a protocol class with the factory.</summary>
class procedure RegisterProtocol(const ClassRef: TProtocolClass);
end;
type
/// <summary>
/// Exception class for use in TProtocol descendant classes.
/// </summary>
EProtocol = class(ECodeSnip);
implementation
{
NOTES
-----
In this program we don't want the browser control to perform its default
activity when certain URLs are clicked, that is we don't want the browser
control to display the referenced URL in its window. We may want to intercept
the URL and perform special processing depending on the URL's protocol.
In addition to performing custom processing on some standard URL protocols,
the program also defines its own "fake" protocols that have special meaning.
The technique used is to define a series of classes that descend from the
TProtocol abstract class. There is a separate class for each supported
protocol and each class knows how to handle its own protocol. Each class
registers itself with TProtocolFactory.
TProtocol.SupportsProtocol must return True if the class handles a protocol
or False if not. The first of the registered TProtocol sub classes to return
True from its SupportsProtocol method is used to handle the protocol and its
TProtcol.Execute method is called.
The TProtocol.Execute method must return True if it handles a protocol and
wishes to inhibit further processing. Code using the protocol classes must
prevent the browser from displaying the URL if Execute returns True but must
allow the browser control to process the URL normally if Execute returns
False.
A static factory class is provided that analyses URLs and creates the
appropriate TProtocol object, based on the URL's protocol and the registered
handler classes.
}
type
/// <summary>
/// Nul protocol used when there is no suitable handler for a protocol.
/// </summary>
/// <remarks>
/// This object is used to indicate that default handling of protocol by the
/// browser control is to be permitted. To this end the Execute method does
/// nothing and returns false to indicate the protocol was not handled and
/// SupportsProtocol returns false because this handler recognises no
/// protocols.
/// </remarks>
TNulProtocolHandler = class(TProtocol)
public
/// <summary>Checks if this protocol handler handles a URL's protocol.
/// </summary>
/// <remarks>This class handles no protocols so always returned False.
/// </remarks>
class function SupportsProtocol(const URL: string): Boolean; override;
/// <summary>Does nothing because no protocol is handled.</summary>
/// <returns>Boolean. Always returns False.</returns>
function Execute: Boolean; override;
end;
{ TProtocolFactory }
class constructor TProtocolFactory.Create;
begin
fRegistrar := TProtocolRegistrar.Create;
end;
class function TProtocolFactory.CreateHandler(
const URL: string): TProtocol;
var
RegisteredCls: TProtocolClass; // enumerates registered protocol classes
begin
for RegisteredCls in Registrar do
if RegisteredCls.SupportsProtocol(URL) then
Exit(RegisteredCls.Create(URL));
Result := TNulProtocolHandler.Create('');
end;
class destructor TProtocolFactory.Destroy;
begin
fRegistrar.Free;
end;
class procedure TProtocolFactory.RegisterProtocol(
const ClassRef: TProtocolClass);
begin
Registrar.RegisterProtocol(ClassRef);
end;
class function TProtocolFactory.Registrar: TProtocolRegistrar;
begin
Result := fRegistrar;
end;
{ TProtocolFactory.TProtocolRegistrar }
constructor TProtocolFactory.TProtocolRegistrar.Create;
begin
inherited Create;
fRegister := TList<TProtocolClass>.Create;
end;
destructor TProtocolFactory.TProtocolRegistrar.Destroy;
begin
fRegister.Free;
inherited;
end;
function TProtocolFactory.TProtocolRegistrar.GetCount: Integer;
begin
Result := fRegister.Count;
end;
function TProtocolFactory.TProtocolRegistrar.GetEnumerator:
TEnumerator<TProtocolClass>;
begin
Result := fRegister.GetEnumerator;
end;
function TProtocolFactory.TProtocolRegistrar.GetProtocol(
const Idx: Integer): TProtocolClass;
begin
Result := fRegister[Idx];
end;
procedure TProtocolFactory.TProtocolRegistrar.RegisterProtocol(
const ClassRef: TProtocolClass);
begin
fRegister.Add(ClassRef);
end;
{ TProtocol }
constructor TProtocol.Create(const URL: string);
begin
inherited Create;
fURL := URL;
end;
{ TNulProtocolHandler }
function TNulProtocolHandler.Execute: Boolean;
begin
Result := False;
end;
class function TNulProtocolHandler.SupportsProtocol(const URL: string): Boolean;
begin
Result := False;
end;
end.
