CodeSnip Old Code (SVN)

{
 * UWebService.pas
 *
 * A class that provides basic interaction with web services via HTTP, a
 * subclass that interacts with standard DelphiDabbler web services and some
 * exception classes raised by various kinds of web server error.
 *
 * $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 UWebService.pas
 *
 * The Initial Developer of the Original Code is Peter Johnson
 * (http://www.delphidabbler.com/).
 *
 * Portions created by the Initial Developer are Copyright (C) 2005-2009 Peter
 * Johnson. All Rights Reserved.
 *
 * Contributor(s)
 *   NONE
 *
 * ***** END LICENSE BLOCK *****
}


unit UWebService;


interface


uses
  // Delphi
  SysUtils, Classes,
  // Indy
  IdHTTP, IdException, IdAntiFreeze,
  // Project
  UExceptions, UDownloadMonitor, UWebInfo;


type

  {
  TWebServiceProgressEvent:
    Type of event handler used to handle TWebService.OnProgress events. Used to
    monitor download progress.
      @param Sender [in] Reference to TWebService object triggering event.
      @param BytesToDate [in] Number of bytes downloaded.
      @param BytesExpected [in] Total number of bytes to be downloaded.
  }
  TWebServiceProgressEvent = procedure(Sender: TObject; const BytesToDate,
    BytesExpected: Integer) of object;

  {
  TWebService:
    Class that provides basic interaction with web services via HTTP. Assumes
    that all responses will have Mime type of 'text/*'.
  }
  TWebService = class(TObject)
  strict private
    fHTTP: TIdHTTP;                         // Fsed to access server via HTTP
    fScriptURI: string;                     // URI of web service script
    fDownloadMonitor: TDownloadMonitor;     // Monitors download progress
    fOnProgress: TWebServiceProgressEvent;  // OnProgress event handler
    fAntiFreeze: TIdAntiFreeze;
  strict protected
    procedure TriggerProgressEvent;
      {Triggers OnProgress event. Helper method provided to be called by
      descendant classes for operations where monitoring of download progress is
      required.
      }
    procedure DoProgress; virtual;
      {Called when download progress information changes. Does nothing.
      Descendants can trigger OnProgress events by calling the
      TriggerProgressEvent method.
      }
    procedure HandleException(const E: EIdException);
      {Handles likely exceptions generated by HTTP component and translates into
      own exception objects that are not detected as bugs and have more user
      friendly error messages.
        @param E [in] Exception to translate.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EWebConnectionError raised if EIdSocketError encoutered.
        @except EIdException or descendants re-raised for other exception types.
      }
    function CreateQueryStrings(const Cmd: string;
      const Params: array of string): TStrings;
      {Creates a string list containing query strings to be sent to server. Note
      that this TStrings object must be freed by caller.
        @param Cmd [in] Command to be executed. Passed to server as Cmd=CmdName
          parameter.
        @param Params [in] List of parameters in form ParamName=ParamValue. []
          if no parameters.
        @return String list containing query strings to be sent to server.
      }
    procedure PostCommand(const Cmd: string; const Params: array of string;
      const Response: TStrings); virtual;
      {Sends a command to server and returns lines of response in a string list.
        @param Cmd [in] Command to be executed. Passed to server as Cmd=CmdName
          parameter.
        @param Params [in] List of parameters in form ParamName=ParamValue. []
          if no parameters.
        @param Response [in] Server's response as string list where each line of
          response is a line of string list.
        @except EWebConnectionError raised if EIdSocketError encoutered.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EIdException or descendant re-raised for other exception types.
      }
    procedure PostQuery(const QS: TStrings; const Response: TStrings); virtual;
      {Sends a query string to server and returns lines of response in a string
      list.
        @param QS [in] List of parameters in Name=Value format.
        @param Response [in] Server's response as string list where each line of
          response is a line of string list.
        @except EWebConnectionError raised if EIdSocketError encoutered.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EIdException or descendant re-raised for other exception types.
      }
    procedure PostData(const Data: TStream; const Response: TStrings); virtual;
      {Posts raw data to server and returns lines of response in a string list.
        @param Data [in] Stream containing raw data to be posted.
        @param Response [in] Server's response as string list where each line of
          response is a line of string list.
        @except EWebConnectionError raised if EIdSocketError encoutered.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EIdException or descendant re-raised for other exception types.
      }
  public
    constructor Create(const Service: TWebServiceInfo);
      {Class constructor. Sets up object.
        @param Service [in] Description of web service.
      }
    destructor Destroy; override;
      {Class destructor. Tears down object.
      }
    property OnProgress: TWebServiceProgressEvent
      read fOnProgress write fOnProgress;
      {Event that can be triggered to monitor progress of downloads. Not
      triggered by default. Descendant classes can trigger the event by
      overriding the DoProgress method and calling TriggerProgressEvent inside
      the overridden method}
  end;

  {
  TDDabStdWebService:
    Web service class that interacts with standard DelphiDabbler web services.
    These services always place a numeric status code in first line of response
    followed by any resulting data. Status code is zero for normal responses and
    non-zero when an error response is returned. This class outputs data for
    normal responses and generates EWebServiceError exceptions for error
    responses, using the response data as the error message. Malformed responses
    generate EWebServiceFailure exceptions.
  }
  TDDabStdWebService = class(TWebService)
  strict protected
    procedure ProcessResponse(const Response: TStrings);
      {Analyses lines of text returned from from web service and extracts data
      from successful responses. Raises exceptions based on error messages from
      error responses.
        @param Response [in] Receives lines of text received as response from
          web service. After processing error code is removed from top of list,
          leaving only returned data.
        @except Raises [in] EWebServiceFailure if response from web service has
          invalid format.
        @except Raises EWebServiceError on receipt of valid error response.
      }
    procedure PostCommand(const Cmd: string; const Params: array of string;
      const Response: TStrings); override;
      {Sends command to server and returns data component of response in a
      string list.
        @param Cmd [in] Command to be executed. Passed to server as Cmd=CmdName
          parameter.
        @param Params [in] List of parameters in form ParamName=ParamValue. []
          if no parameters.
        @param Response [in] Server's response as string list where each line of
          response is a line of string list.
        @except EWebServiceError raised on receipt of valid error response.
        @except EWebServiceFailure raised if web service sends invalid response.
        @except EWebConnectionError raised EIdSocketError encoutered.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EIdException or descendant re-raised for other exception types.
      }
    procedure PostQuery(const QS: TStrings; const Response: TStrings);
      override;
      {Sends a query string to server and returns data component of response in
      a string list.
        @param QS [in] List of parameters in Name=Value format.
        @param Response [in] Server's response as string list where each line of
          response is a line of string list.
        @except EWebServiceError raised on receipt of valid error response.
        @except EWebServiceFailure raised if web service sends invalid response.
        @except EWebConnectionError raised EIdSocketError encoutered.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EIdException or descendant re-raised for other exception types.
      }
    procedure PostData(const Data: TStream; const Response: TStrings); override;
      {Posts raw data to server and returns data component of response in a
      string list.
        @param Data [in] Stream containing raw data to be posted.
        @param Response [in] Server's response as string list where each line of
          response is a line of string list.
        @except EWebServiceError raised on receipt of valid error response.
        @except EWebServiceFailure raised if web service sends invalid response.
        @except EWebConnectionError raised EIdSocketError encoutered.
        @except EHTTPError raised if EIdHTTPProtocolException encountered.
        @except EIdException or descendant re-raised for other exception types.
      }
  end;

  {
  EWebService:
    Base class for all errors generated by web services. None of these
    exceptions are treated as bugs.
  }
  EWebService = class(ECodeSnip);

  {
  EHTTPError:
    Exception raised when web server HTTP error is detected. Note these errors
    relate to the web server, not the web service.
  }
  EHTTPError = class(EWebService)
  strict private
    fHTTPErrorCode: Integer;  // HTTPErrorCode property value
  public
    constructor Create(const E: EIdHTTPProtocolException); overload;
      {Class constructor. Creates object from properties of given exception.
        @param E [in] Instance of exception from which to create this exception.
          E.ReplyErrorCode is stored in HTTPErrorCode property and E.Message is
          stored in Message property.
      }
    procedure Assign(const E: Exception); override;
      {Assigns properties of another exception to this one.
        @param E [in] Exception whose properties are to be copied. Must be an
          EHTTPError or an EIdHTTPProtocolException instance.
      }
    property HTTPErrorCode: Integer read fHTTPErrorCode;
      {HTTP error code from web server}
  end;

  {
  EWebConnectionError:
    Exception raised when there is a problem connecting to web server (i.e.
    socket error).
  }
  EWebConnectionError = class(EWebService);

  {
  EWebServiceFailure:
    Exception raised when the web service fails to response as expected.
  }
  EWebServiceFailure = class(EWebService);

  {
  EWebServiceError:
    Exception raised when a web service returns an error condition as a response
    to a command. It has a non-zero error code in addition to the error message.
  }
  EWebServiceError = class(EWebService)
  strict private
    fErrorCode: Integer;  // Value of ErrorCode property
  public
    constructor Create(const Msg: string; const ErrorCode: Integer = -1);
      overload;
      {Class constructor. Constructs exception object with an error code in
      addition to standard error message.
        @param Message [in] Error message.
        @param ErrorCode [in] Optional non-zero error code (defaults to -1).
      }
    constructor CreateFmt(const Fmt: string; const Args: array of const;
      const ErrorCode: Integer = -1); overload;
      {Class constructor. Constructs exception object with an error code in
      addition to message built from format string and arguments.
        @param Fmt [in] Format for message string.
        @param Args [in] Arguments to be included in formatted message string.
        @param ErrorCode [in] Optional non-zero error code (defaults to -1).
      }
    procedure Assign(const E: Exception); override;
      {Assigns properties of another exception to this one.
        @param E [in] Exception whose properties are to be copied. Must be an
          EWebServiceError instance.
      }
    property ErrorCode: Integer read fErrorCode;
      {Non-zero error code}
  end;


implementation


uses
  // Indy
  IdStack,
  // Project
  UConsts;


resourcestring
  // Error messages
  sWebConnectionError = 'There was a problem accessing the internet. Please '
    + 'check your web connection. '
    + 'If you are using a proxy server please check its configuration.'
    + EOL2
    + 'The error reported by Windows was: %0:s.';


{ TWebService }

constructor TWebService.Create(const Service: TWebServiceInfo);
  {Class constructor. Sets up object.
    @param Service [in] Description of web service.
  }
var
  ProxyInfo: TWebProxyInfo; // details on any proxy server
begin
  inherited Create;
  // Use anti-freeze component to enable message loop to continue while
  // Indy components block.
  fAntiFreeze := TIdAntiFreeze.Create(nil);
  // Create and initialise HTTP client component
  fHTTP := TIdHTTP.Create(nil);
  fHTTP.Request.UserAgent := Service.UserAgent;
  fHTTP.Request.Accept := Service.MediaType;
  ProxyInfo := TWebInfo.WebProxyInfo;
  if ProxyInfo.UseProxy then
  begin
    fHTTP.ProxyParams.ProxyServer := ProxyInfo.IPAddress;
    fHTTP.ProxyParams.ProxyPort := ProxyInfo.Port;
    fHTTP.ProxyParams.ProxyUsername := ProxyInfo.UserName;
    fHTTP.ProxyParams.ProxyPassword := ProxyInfo.Password;
  end;
  // Create object that monitors download progress
  fDownloadMonitor := TDownloadMonitor.Create(fHTTP, DoProgress);
  // Record script URI for future use
  fScriptURI := Service.ScriptURI;
end;

function TWebService.CreateQueryStrings(const Cmd: string;
  const Params: array of string): TStrings;
  {Creates a string list containing query strings to be sent to server. Note
  that this TStrings object must be freed by caller.
    @param Cmd [in] Command to be executed. Passed to server as Cmd=CmdName
      parameter.
    @param Params [in] List of parameters in form ParamName=ParamValue. [] if no
      parameters.
    @return String list containing query strings to be sent to server.
  }
var
  I: Integer; // loops through parameters
begin
  Result := TStringList.Create;
  Result.Add('cmd=' + Cmd);
  for I := Low(Params) to High(Params) do
    Result.Add(Params[I]);
end;

destructor TWebService.Destroy;
  {Class destructor. Tears down object.
  }
begin
  FreeAndNil(fDownloadMonitor);
  FreeAndNil(fHTTP);
  FreeAndNil(fAntiFreeze);
  inherited;
end;

procedure TWebService.DoProgress;
  {Called when download progress information changes. Does nothing. Descendants
  can trigger OnProgress events by calling the TriggerProgressEvent method.
  }
begin
  // Do nothing: descendant may call TriggerProgressEvent here if event required
  // (or do any other required processing)
end;

procedure TWebService.HandleException(const E: EIdException);
  {Handles likely exceptions generated by HTTP component and translates into own
  exception objects that are not detected as bugs and have more user friendly
  error messages.
    @param E [in] Exception to translate.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EWebConnectionError raised if EIdSocketError encoutered.
    @except EIdException or descendants re-raised for other exception types.
  }
begin
  if E is EIdHTTPProtocolException then
    raise EHTTPError.Create(E as EIdHTTPProtocolException)
  else if E is EIdSocketError then
    raise EWebConnectionError.CreateFmt(sWebConnectionError, [Trim(E.Message)])
  else
    raise E;
end;

procedure TWebService.PostCommand(const Cmd: string;
  const Params: array of string; const Response: TStrings);
  {Sends a command to server and returns lines of response in a string list.
    @param Cmd [in] Command to be executed. Passed to server as Cmd=CmdName
      parameter.
    @param Params [in] List of parameters in form ParamName=ParamValue. [] if no
      parameters.
    @param Response [in] Server's response as string list where each line of
      response is a line of string list.
    @except EWebConnectionError raised if EIdSocketError encoutered.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EIdException or descendant re-raised for other exception types.
  }
var
  QS: TStrings; // list of query strings
begin
  QS := CreateQueryStrings(Cmd, Params);
  try
    PostQuery(QS, Response);
  finally
    FreeAndNil(QS);
  end;
end;

procedure TWebService.PostData(const Data: TStream; const Response: TStrings);
  {Posts raw data to server and returns lines of response in a string list.
    @param Data [in] Stream containing raw data to be posted.
    @param Response [in] Server's response as string list where each line of
      response is a line of string list.
    @except EWebConnectionError raised if EIdSocketError encoutered.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EIdException or descendant re-raised for other exception types.
  }
begin
  try
    Response.Text := fHTTP.Post(fScriptURI, Data);
  except
    on E: EIdException do
      HandleException(E);
  end;
end;

procedure TWebService.PostQuery(const QS, Response: TStrings);
  {Sends a query string to server and returns lines of response in a string
  list.
    @param QS [in] List of parameters in Name=Value format.
    @param Response [in] Server's response as string list where each line of
      response is a line of string list.
    @except EWebConnectionError raised if EIdSocketError encoutered.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EIdException or descendant re-raised for other exception types.
  }
begin
  try
    Response.Text := fHTTP.Post(fScriptURI, QS);
  except
    on E: EIdException do
      HandleException(E);
  end;
end;

procedure TWebService.TriggerProgressEvent;
  {Triggers OnProgress event. Helper method provided to be called by descendant
  classes for operations where monitoring of download progress is required.
  }
begin
  if Assigned(fOnProgress) then
    fOnProgress(
      Self, fDownloadMonitor.BytesReceived, fDownloadMonitor.BytesExpected
    );
end;

{ TDDabStdWebService }

resourcestring
  // Error messages
  sEmptyResponse = 'Empty response received from web service';
  sBadStatusCode = 'Web service returned response with bad status code';
  sUnrecognizedError = 'Unrecognized error notified by web service';

procedure TDDabStdWebService.PostCommand(const Cmd: string;
  const Params: array of string; const Response: TStrings);
  {Sends command to server and returns data component of response in a string
  list.
    @param Cmd [in] Command to be executed. Passed to server as Cmd=CmdName
      parameter.
    @param Params [in] List of parameters in form ParamName=ParamValue. [] if no
      parameters.
    @param Response [in] Server's response as string list where each line of
      response is a line of string list.
    @except EWebServiceError raised on receipt of valid error response.
    @except EWebServiceFailure raised if web service sends invalid response.
    @except EWebConnectionError raised EIdSocketError encoutered.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EIdException or descendant re-raised for other exception types.
  }
begin
  inherited; // Calls this class' version of PostQuery
end;

procedure TDDabStdWebService.PostData(const Data: TStream;
  const Response: TStrings);
  {Posts raw data to server and returns data component of response in a string
  list.
    @param Data [in] Stream containing raw data to be posted.
    @param Response [in] Server's response as string list where each line of
      response is a line of string list.
    @except EWebServiceError raised on receipt of valid error response.
    @except EWebServiceFailure raised if web service sends invalid response.
    @except EWebConnectionError raised EIdSocketError encoutered.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EIdException or descendant re-raised for other exception types.
  }
begin
  inherited;
  ProcessResponse(Response);
end;

procedure TDDabStdWebService.PostQuery(const QS, Response: TStrings);
  {Sends a query string to server and returns data component of response in a
  string list.
    @param QS [in] List of parameters in Name=Value format.
    @param Response [in] Server's response as string list where each line of
      response is a line of string list.
    @except EWebServiceError raised on receipt of valid error response.
    @except EWebServiceFailure raised if web service sends invalid response.
    @except EWebConnectionError raised EIdSocketError encoutered.
    @except EHTTPError raised if EIdHTTPProtocolException encountered.
    @except EIdException or descendant re-raised for other exception types.
  }
begin
  inherited;
  ProcessResponse(Response);
end;

procedure TDDabStdWebService.ProcessResponse(const Response: TStrings);
  {Analyses lines of text returned from from web service and extracts data from
  successful responses. Raises exceptions based on error messages from error
  responses.
    @param Response [in] Receives lines of text received as response from web
      service. After processing error code is removed from top of list, leaving
      only returned data.
    @except Raises [in] EWebServiceFailure if response from web service has
      invalid format.
    @except Raises EWebServiceError on receipt of valid error response.
  }
var
  StatusCode: Integer; // status code from response
begin
  // All responses have content => empty reponse is error
  if Response.Count = 0 then
    raise EWebServiceFailure.Create(sEmptyResponse);
  // All valid responses have status code as first line of response
  if not TryStrToInt(Response[0], StatusCode) then
    raise EWebServiceFailure.Create(sBadStatusCode);
  // We have got status code: chop it off to leave data in Response
  Response.Delete(0);
  // Check status code in first line: 0 => OK, otherwise error
  if StatusCode <> 0 then
  begin
    // Error response
    // data should contain error message
    if Trim(Response.Text) = '' then
      // no error message
      raise EWebServiceFailure.Create(sUnrecognizedError);
    // valid error message: raise exception using it
    raise EWebServiceError.Create(Trim(Response.Text), StatusCode);
  end
end;

{ EHTTPError }

procedure EHTTPError.Assign(const E: Exception);
  {Assigns properties of another exception to this one.
    @param E [in] Exception whose properties are to be copied. Must be an
      EHTTPError or an EIdHTTPProtocolException instance.
  }
begin
  Assert((E is EHTTPError) or (E is EIdHTTPProtocolException),
    ClassName + '.Assign: E must be EHTTPError or EIdHTTPProtocolException');
  inherited;
  if E is EHTTPError then
    fHTTPErrorCode := (E as EHTTPError).fHTTPErrorCode
  else
    fHTTPErrorCode := (E as EIdHTTPProtocolException).ErrorCode;
end;

constructor EHTTPError.Create(const E: EIdHTTPProtocolException);
  {Class constructor. Creates object from properties of given exception.
    @param E [in] Instance of exception from which to create this exception.
      E.ReplyErrorCode is stored in HTTPErrorCode property and E.Message is
      stored in Message property.
  }
begin
  inherited Create(E.Message);
  fHTTPErrorCode := E.ErrorCode; 
end;

{ EWebServiceError }

procedure EWebServiceError.Assign(const E: Exception);
  {Assigns properties of another exception to this one.
    @param E [in] Exception whose properties are to be copied. Must be an
      EWebServiceError instance.
  }
begin
  Assert(E is EWebServiceError,
    ClassName + '.Assign: E must be EWebServiceError');
  inherited;
  fErrorCode := (E as EWebServiceError).fErrorCode;
end;

constructor EWebServiceError.Create(const Msg: string;
  const ErrorCode: Integer);
  {Class constructor. Constructs exception object with an error code in addition
  to standard error message.
    @param Message [in] Error message.
    @param ErrorCode [in] Optional non-zero error code (defaults to -1).
  }
begin
  Assert(ErrorCode <> 0, ClassName + '.Create: zero error code');
  inherited Create(Msg);
  fErrorCode := ErrorCode;
end;

constructor EWebServiceError.CreateFmt(const Fmt: string;
  const Args: array of const; const ErrorCode: Integer);
  {Class constructor. Constructs exception object with an error code in addition
  to message built from format string and arguments.
    @param Fmt [in] Format for message string.
    @param Args [in] Arguments to be included in formatted message string.
    @param ErrorCode [in] Optional non-zero error code (defaults to -1).
  }
begin
  Assert(ErrorCode <> 0, ClassName + '.CreateFmt: zero error code');
  Create(Format(Fmt, Args), ErrorCode);
end;

end.