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) 2013, Peter Johnson (www.delphidabbler.com).
 *
 * $Rev$
 * $Date$
 *
 * Implements a class that interfaces with the DelphiDabbler SWAG web service.
 * For details of the web service see http://swag.delphidabbler.com/docs/api/
}


unit Web.USWAGRESTMgr;


interface


uses
  // Delphi
  XMLIntf,
  Generics.Collections,
  // Project
  Web.UBaseWebService,
  UXMLDocumentEx,
  UURIParams,
  SWAG.UCommon;


type
  TSWAGRESTRange = record
    Start: Cardinal;
    Length: Cardinal;
    constructor Create(AStart: Cardinal; ALength: Cardinal);
    class function CreateNull: TSWAGRESTRange; static;
    function IsNull: Boolean;
    function ToString: string;
  end;

type
  TSWAGRESTMgr = class sealed(TBaseWebService)
  strict private
    const
      ///  <summary>Web service's base URL template.</summary>
      ScriptURLTplt = 'http://swag.%s/api/v1';
      ///  <summary>User agent sent to web service.</summary>
      UserAgent = 'CodeSnip';
    procedure AddLimitParam(Params: TURIParams; const Range: TSWAGRESTRange);
    procedure AddFieldsParam(Params: TURIParams; const Fields: array of string);
    function CreateParams: TURIParams;
    procedure ParseSnippetNode(XMLDoc: IXMLDocumentEx; Node: IXMLNode;
      out Snippet: TSWAGSNippet);
    procedure ValidateResponse(XMLDoc: IXMLDocumentEx);
    function CreateValidXMLDoc(const XML: string): IXMLDocumentEx;
    procedure ParseCategoriesResponse(const XML: string;
      CatList: TList<TSWAGCategory>);
    procedure ParseSnippetsResponse(const XML: string;
      SnippetList: TList<TSWAGSnippet>);
    procedure ParseSnippetResponse(const XML: string;
      out Snippet: TSWAGSnippet);
    function ParseSnippetCount(const XML: string): Cardinal;
  public
    constructor Create;
    procedure GetCategories(CatList: TList<TSWAGCategory>);
    procedure GetSnippets(const CatID: string; const Fields: array of string;
      const Limit: TSWAGRESTRange; SnippetList: TList<TSWAGSnippet>);
      overload;
    procedure GetSnippets(const CatID: string; const Fields: array of string;
      SnippetList: TList<TSWAGSnippet>); overload;
    procedure GetSnippets(const Fields: array of string;
      const Limit: TSWAGRESTRange; SnippetList: TList<TSWAGSnippet>); overload;
    procedure GetSnippets(const Fields: array of string;
      SnippetList: TList<TSWAGSnippet>); overload;
    procedure GetSnippet(const SnippetID: Cardinal;
      const Fields: array of string; out Snippet: TSWAGSnippet);
    function GetSnippetCount(const CatID: string = '*'): Cardinal;
  end;


implementation


uses
  // Delphi
  SysUtils,
  // Project
  UIStringList,
  UStrUtils,
  UURIEncode,
  UUtils,
  UXMLDocHelper,
  Web.UInfo,
  Web.UExceptions;


{ TSWAGRESTMgr }

procedure TSWAGRESTMgr.AddFieldsParam(Params: TURIParams;
  const Fields: array of string);
var
  FieldList: IStringList;
begin
  FieldList := TIStringList.Create(Fields);
  Params.Add('fields', FieldList.GetText(',', False));
end;

procedure TSWAGRESTMgr.AddLimitParam(Params: TURIParams;
  const Range: TSWAGRESTRange);
begin
  Params.Add('limit', Range.ToString);
end;

constructor TSWAGRESTMgr.Create;
begin
  inherited Create(TWebServiceInfo.Create(ScriptURLTplt, UserAgent));
end;

function TSWAGRESTMgr.CreateParams: TURIParams;
begin
  Result := TURIParams.Create;
  Result.Add('format', 'xml');
  Result.Add('suppressResponseCodes', 'true');
end;

function TSWAGRESTMgr.CreateValidXMLDoc(const XML: string): IXMLDocumentEx;
begin
  Result := TXMLDocumentEx.Create(nil);
  Result.LoadFromXML(XML);
  ValidateResponse(Result);
end;

procedure TSWAGRESTMgr.GetCategories(CatList: TList<TSWAGCategory>);
const
  ResourcePath = 'categories';
var
  Params: TURIParams;
  Response: string;
begin
  Params := CreateParams;
  try
    Response := GetText(ResourcePath, Params);
    ParseCategoriesResponse(Response, CatList);
  finally
    Params.Free;
  end;
end;

procedure TSWAGRESTMgr.GetSnippet(const SnippetID: Cardinal;
  const Fields: array of string; out Snippet: TSWAGSnippet);
const
  ResourcePathTplt = 'snippet/%d';
var
  Params: TURIParams;
  Response: string;
begin
  Params := CreateParams;
  try
    AddFieldsParam(Params, Fields);
    Response := GetText(Format(ResourcePathTplt, [SnippetID]), Params);
    ParseSnippetResponse(Response, Snippet);
  finally
    Params.Free;
  end;
end;

function TSWAGRESTMgr.GetSnippetCount(const CatID: string): Cardinal;
const
  ResourcePathTplt = 'snippet-count/%s';
var
  Params: TURIParams;
  Response: string;
begin
  Params := CreateParams;
  try
    Response := GetText(Format(ResourcePathTplt, [URIEncode(CatID)]), Params);
    Result := ParseSnippetCount(Response);
  finally
    Params.Free;
  end;
end;

procedure TSWAGRESTMgr.GetSnippets(const CatID: string;
  const Fields: array of string; const Limit: TSWAGRESTRange;
  SnippetList: TList<TSWAGSnippet>);
const
  ResourcePathTplt = 'snippets/%s';
var
  Params: TURIParams;
  Response: string;
begin
  Params := CreateParams;
  try
    AddFieldsParam(Params, Fields);
    if not Limit.IsNull then
      AddLimitParam(Params, Limit);
    Response := GetText(Format(ResourcePathTplt, [URIEncode(CatID)]), Params);
    ParseSnippetsResponse(Response, SnippetList);
  finally
    Params.Free;
  end;
end;

procedure TSWAGRESTMgr.GetSnippets(const CatID: string;
  const Fields: array of string; SnippetList: TList<TSWAGSnippet>);
begin
  GetSnippets(CatID, Fields, TSWAGRESTRange.CreateNull, SnippetList);
end;

procedure TSWAGRESTMgr.GetSnippets(const Fields: array of string;
  SnippetList: TList<TSWAGSnippet>);
begin
  GetSnippets('*', Fields, SnippetList);
end;

procedure TSWAGRESTMgr.GetSnippets(const Fields: array of string;
  const Limit: TSWAGRESTRange; SnippetList: TList<TSWAGSnippet>);
begin
  GetSnippets('*', Fields, Limit, SnippetList);
end;

procedure TSWAGRESTMgr.ParseCategoriesResponse(const XML: string;
  CatList: TList<TSWAGCategory>);
var
  XMLDOc: IXMLDocumentEx;
  CategoriesNode: IXMLNode;
  CategoryNodes: IXMLSimpleNodeList;
  CategoryNode: IXMLNode;
  Category: TSWAGCategory;
resourcestring
  sCategoriesNodeMissing = 'Response has no category information';
begin
  XMLDoc := CreateValidXMLDoc(XML);
  CategoriesNode := XMLDoc.FindNode('response\categories');
  if not Assigned(CategoriesNode) then
    raise EWebServiceFailure.Create(sCategoriesNodeMissing);
  CategoryNodes := XMLDoc.FindChildNodes(CategoriesNode, 'category');
  for CategoryNode in CategoryNodes do
  begin
    Category.ID := TXMLDocHelper.GetSubTagText(XMLDoc, CategoryNode, 'id');
    Category.Title := TXMLDocHelper.GetSubTagText(
      XMLDoc, CategoryNode, 'title'
    );
    CatList.Add(Category);
  end;
end;

function TSWAGRESTMgr.ParseSnippetCount(const XML: string): Cardinal;
var
  XMLDOc: IXMLDocumentEx;
  CountNode: IXMLNode;
resourcestring
  sBadCountNode = 'Response has missing or invalid count information';
begin
  XMLDoc := CreateValidXMLDoc(XML);
  CountNode := XMLDoc.FindNode('response\snippetCount');
  if not Assigned(CountNode)
    or not CountNode.IsTextElement
    or not TryStrToCardinal(CountNode.Text, Result) then
    raise EWebServiceFailure.Create(sBadCountNode);
end;

procedure TSWAGRESTMgr.ParseSnippetNode(XMLDoc: IXMLDocumentEx; Node: IXMLNode;
  out Snippet: TSWAGSNippet);
var
  NumStr: string;
  DateStr: string;
resourcestring
  sBadID = 'Invalid value for snippet id';
  sBadFileNumber = 'Invalid value for snippet file number';
begin
  NumStr := TXMLDocHelper.GetSubTagText(XMLDoc, Node, 'id');
  if NumStr <> '' then
  begin
    if not TryStrToCardinal(NumStr, Snippet.ID) then
      raise EWebServiceFailure.Create(sBadID);
  end
  else
    Snippet.ID := 0;

  Snippet.Category := TXMLDocHelper.GetSubTagText(XMLDoc, Node, 'category');

  Snippet.FileName := TXMLDocHelper.GetSubTagText(XMLDoc, Node, 'file_name');

  DateStr := TXMLDocHelper.GetSubTagText(XMLDoc, Node, 'datestamp');
  if DateStr <> '' then
    Snippet.DateStamp := ParseSQLDateTime(DateStr)
  else
    Snippet.DateStamp := 0.0;

  Snippet.Title := TXMLDocHelper.GetSubTagText(XMLDoc, Node, 'title');

  Snippet.Author := TXMLDocHelper.GetSubTagText(XMLDoc, Node, 'author');

  Snippet.SourceCode := TXMLDocHelper.GetSubTagText(
    XMLDoc, Node, 'source_code'
  );

  Snippet.IsDocument := StrMatchText(
    TXMLDocHelper.GetSubTagText(XMLDoc, Node, 'is_document'),
    ['1', 'yes', 'y', 'true']
  );
end;

procedure TSWAGRESTMgr.ParseSnippetResponse(const XML: string;
  out Snippet: TSWAGSnippet);
var
  XMLDoc: IXMLDocumentEx;
  SnippetNode: IXMLNode;
resourcestring
  sSnippetNodeMissing = 'Response has no snippet information';
begin
  XMLDoc := CreateValidXMLDoc(XML);
  SnippetNode := XMLDoc.FindNode('response\snippet');
  if not Assigned(SnippetNode) then
    raise EWebServiceFailure.Create(sSnippetNodeMissing);
  ParseSnippetNode(XMLDoc, SnippetNode, Snippet);
end;

procedure TSWAGRESTMgr.ParseSnippetsResponse(const XML: string;
  SnippetList: TList<TSWAGSnippet>);
var
  XMLDOc: IXMLDocumentEx;
  SnippetsNode: IXMLNode;
  SnippetNodes: IXMLSimpleNodeList;
  SnippetNode: IXMLNode;
  Snippet: TSWAGSnippet;
resourcestring
  sSnippetsNodeMissing = 'Response has no snippets information';
begin
  XMLDoc := CreateValidXMLDoc(XML);
  SnippetsNode := XMLDoc.FindNode('response\snippets');
  if not Assigned(SnippetsNode) then
    raise EWebServiceFailure.Create(sSnippetsNodeMissing);
  SnippetNodes := XMLDoc.FindChildNodes(SnippetsNode, 'snippet');
  for SnippetNode in SnippetNodes do
  begin
    ParseSnippetNode(XMLDoc, SnippetNode, Snippet);
    SnippetList.Add(Snippet);
  end;
end;

procedure TSWAGRESTMgr.ValidateResponse(XMLDoc: IXMLDocumentEx);
resourcestring
  sMissingRootNode = 'Response root node not found';
  sBadStatus = 'Response status missing or invalid';
  sMissingErrInfo = 'Error information missing';
  sBadErrStatus = 'Error status code missing or mal-formed';
  sBadErrCode = 'Error code missing or mal-formed';
  sMissingErrMessage = 'Error message missing';
var
  RootNode: IXMLNode;
  Status: string;
  ErrNode: IXMLNode;
  ErrStatus: Integer;
  ErrCode: Integer;
  ErrMessage: string;
begin
  TXMLDocHelper.ValidateProcessingInstr(XMLDoc);
  RootNode := XMLDoc.FindNode('response');
  if not Assigned(RootNode) then
    raise EWebServiceFailure.Create(sMissingRootNode);
  Status := TXMLDocHelper.GetSubTagText(XMLDoc, RootNode, 'status');
  if not StrSameText(Status, 'ok') and not StrSameText(Status, 'error') then
    raise EWebServiceFailure.Create(sBadStatus);
  if StrSameText(Status, 'ok') then
    Exit;
  // we have error response - validate response and get details (don't validate
  // 'response\error\status' node since we don't make use of it).
  ErrNode := XMLDoc.FindNode('response\error');
  if not Assigned(ErrNode) then
    raise EWebServiceFailure(sMissingErrInfo);
  if not TryStrToInt(
    TXMLDocHelper.GetSubTagText(XMLDOc, ErrNode, 'status'), ErrStatus
  ) then
    raise EWebServiceFailure.Create(sBadErrStatus);
  if not TryStrToInt(
    TXMLDocHelper.GetSubTagText(XMLDoc, ErrNode, 'code'), ErrCode
  ) then
    raise EWebServiceFailure.Create(sBadErrCode);
  ErrMessage := TXMLDocHelper.GetSubTagText(XMLDoc, ErrNode, 'message');
  if ErrMessage = '' then
    raise EWebServiceFailure.Create(sMissingErrMessage);
  // error response is valid: raise exception for message and code
  raise EWebServiceError.Create(ErrMessage, ErrCode);
end;

{ TSWAGRESTRange }

constructor TSWAGRESTRange.Create(AStart, ALength: Cardinal);
begin
  Start := AStart;
  Length := ALength;
end;

class function TSWAGRESTRange.CreateNull: TSWAGRESTRange;
begin
  Result := TSWAGRESTRange.Create(0, 0);
end;

function TSWAGRESTRange.IsNull: Boolean;
begin
  Result := Length = 0;
end;

function TSWAGRESTRange.ToString: string;
begin
  Result := Format('%d,%d', [Start, Length]);
end;

end.