Amazon.com Widgets June 2012

TVirtualInterface: A Truly Dynamic and Even Useful Example

By Nick at June 30, 2012 17:25
Filed Under: Delphi, Software Development, Unit Testing

Introduction

This is the third article in a series about using TVirtualInterface.  The two previous articles are TVirtualInterface: Interfaces without an Implementing Class and TVirtualInterface: Next Steps.

Okay, enough with the not-all-that-useful examples.  I mean, the previous articles were illustrative, but not really “real-world useful”.

The true usefulness of TVirtualInterface occurs when you use it to create code where you have no idea what interface the user of your code is going to try to implement.  All the examples so far have shown only implementing classes where you do know which interface is being used.  The exception so far is the TReportingVirtualInterface example which reports information on any interface you pass to it.  Since we have proven that you can use TVirtualInterface to do something useful, let’s take it a step further.

A practical use of TVirtualInterface is to create a mocking library for unit testing.  I’ve mentioned numerous times the Delphi Mocks Framework by Vince Parrett of FinalBuilder fame.  Another excellent implementation of a mocking framework (as well as a bunch of other very innovative and interesting stuff) is by Stefan Glienke as part of his Delphi Sorcery framework.  Both of these use TVirtualInterface to provide a mock implementation for any interface (though the Delphi Sorcery code implements its own version of TVirtualInterface that works with Delphi XE – very cool).  Both, of course, allow you to pass them any interface, and they’ll happily mock your interface for unit testing purposes.  So why not do an example here of a very simple mocking object that you can actually use if you want?

ISimpleStub

A while back I wrote an article called The Vocabulary of Unit Testing.  In it I described the distinction between a stub and a mock.  I defined a “stub” as “a fake that has no effect on the passing or failing of the test, and that exists purely to allow the test to run.”  So, how about we build a universal stub – a class that can pretend to be any interface you want, and not do anything at all.  That can’t be that tough, can it?

Well, we already have a class that can implement an interface, but we need to find a way for that class to actually be the interface.  If you want a stub, the stub has to actually be the interface type you are trying to stub out, right?

First, since we always code against abstractions, let’s declare an interface:

  ISimpleStub<T> = interface
  ['{6AA7C2F0-E62F-497B-9A77-04D6F369A288}']
    function InterfaceToCall: T;
  end;

And then let’s implement it with a descendent of TVirtualInterfaceEx<T>:

  TSimpleStub<T: IInvokable> = class(TVirtualInterfaceEx<T>, ISimpleStub<T>)
  protected
    procedure DoInvokeImpl(Method: TRttiMethod;  const Args: TArray<TValue>; out Result: TValue); override;
  public
    function InterfaceToCall: T;
  end;

Because TSimpleStub<T> descends from TVirtualInterfaceEx<T>, it can implement any interface you pass to it.  It thus overrides DoInvokeImpl from  TVirtualInterfaceEx<T> as well as implementing InterfaceToCall from ISimpleStub<T>.

First, let’s look at DoInvokeImpl:

procedure TSimpleStub<T>.DoInvokeImpl(Method: TRttiMethod; const Args: TArray<TValue>; out Result: TValue);
begin
  // Since this is a pure stub, don't do anything!
end;

Not much to see here  – it doesn’t do anything.  And for a stub, that is fine.  That’s exactly what stubs are supposed to do – nothing.  We don’t care what happens when the methods get called, you just need to actually be able to call them.

That’s where the InterfaceToCall function comes in.  The class knows about the type of interface being stubbed because we are passing that type in as a parameterized type.  The class itself knows how to implement that interface.  There has to be a way to get an actual reference to that implemented interface, right?  This is where the InterfaceToCall method comes in:

function TSimpleStub<T>.InterfaceToCall: T;
var
  pInfo : PTypeInfo;
begin
  pInfo := TypeInfo(T);
  if QueryInterface(GetTypeData(pInfo).Guid, Result) <> 0 then
  begin
    raise Exception.CreateFmt('Sorry, TSimpleStub<T> is unable to cast %s to its interface ', [string(pInfo.Name)]);
  end;
end;

Since TSimpleStub<T> knows the type that T is, you can call QueryInterface on the type information about T itself to get a reference to the interface in question.  And of course, once you have that, you can pass that reference anywhere you need to stub out the interface – normally as part of unit testing.

So now, you can safely call methods on the stubbed interface.  For instance, given this interface:

IActuallyUseful = interface(IInvokable)
  ['{16F01BF0-961F-4461-AEBE-B1ACB8D3F0F4}']
  procedure SayHello;
  function ReverseString(aString: string): string;
  function Multiply(x, y: integer): integer;
end;

Writeln('Implementing a TSimpleStub');
SimpleStub := TSimpleStub<IActuallyUseful>.Create;
WriteLn('Nothing should appear between this and the next statement');
SimpleStub.InterfaceToCall.SayHello;
SimpleStub.InterfaceToCall.Multiply(4, 4);
SimpleStub.InterfaceToCall.ReverseString('blah');
WriteLn('Nothing should appear between this and the above statement');
WriteLn;

Nothing happens when you call the interface methods, but that’s by design:  stubs should do nothing.  What you can do is call them as part of your unit testing:

begin
  ...
  MyClassUnderTest := TSprocketThatTakesAnIWhatever.Create(SimpleStub.InterfaceToCall)
  ...
end;

TSimpleMock

Okay, so there’s a useful, dynamic way to use TVirtualInterfaceTSimpleStub<T> will work great for a stub that you expect absolutely nothing from.  But sometimes you need a fake interface that does something more than just existing, and when that is the case, you are creating a mock.  In my unit testing definitions article, I defined a mock as “a fake that keeps track of the behavior of the Class Under Test and passes or fails the test based on that behavior.”  Thus, a mock needs to do more than exist like a stub –  it needs to behave in a way that you can define.   So how about we take TSimpleMock<T> and make it do a basic mocking function – responding in a specific way to a specific input.

One of the most common things that a mock interface does is to respond with “this” when passed “that”.  How about we create a simple mock class that lets you define a specific response to a method call?

First, of course, is an interface to code against:

 

  ISimpleMock<T> = interface(ISimpleStub<T>)
  ['{9619542B-A53B-4C0C-B915-45ED140E6479}']
    procedure AddExpectation(aCallName: string; aReturnValue: TValue);
  end;

The interface augments (“inherits from” is not quite right with interfaces) ISimpleStub<T> and adds the AddExpectation method.  This is the method that we’ll use to tell the mock out to respond when and interface method gets called. 

Here’s the implementing class:

  TSimpleMock<T: IInvokable> = class(TSimpleStub<T>, ISimpleMock<T>)
  private
    FActions: TDictionary<string, TValue>;
  protected
    procedure DoInvokeImpl(Method: TRttiMethod;  const Args: TArray<TValue>; out Result: TValue); override;
  public
    constructor Create;
    destructor Destroy; override;
    procedure AddExpectation(aCallName: string; aReturnValue: TValue);
  end;

The first thing to notice is that TSimpleMock<T> inherits  from TSimpleStub<T>, thus enabling it to “be” any interface it wants as our stub was. And of course it also implements the  AddExpection method.  It takes as parameters the name of the method on the interface that you can call, as well as a return value for when that method gets called.  In this way you can define the behavior of the mock class however you want.

This very simple mocking example assumes that you are going to be mocking only function calls as methods on an interface. Within the confines of our simple example, it doesn’t make sense to mock procedures – they basically don’t do anything as far as the simple example is concerned.  Real mock frameworks are able to keep track of whether a procedure is called, how many times it does get called, and other things associated with procedures.  This simple example also doesn’t care what parameters you pass in, it will merely return a value whenever the named method is called.   Remember, this is a simple – but useful in specific situations -- example.  Winking smile 

The implementation of TSimpleMock<T> is pretty, well, simple.  Internally, it uses a TDictionary<TKey, TValue> to keep track of the method calls and the resulting responses that are added via the AddExpectation call.  Here is the implementation of AddExpectation :

procedure TSimpleMock<T>.AddExpectation(const aCallName: string; aReturnValue: TValue);
begin
  FActions.Add(aCallName, aReturnValue);
end;

When you add an expectation, the class keeps track of it.  When you then call that method on the interface, it is able to retrieve the expected return value from the dictionary and return it:

procedure TSimpleMock<T>.DoInvokeImpl(Method: TRttiMethod; const Args: TArray<TValue>; out Result: TValue);
begin
  Result := FActions[Method.Name];
end;

(The obvious shortcoming here is no error handling – you’ll get an exception if you try to call a method on the interface that doesn’t  have an expectation entry.  Another shortcoming is that the parameters passed mean nothing – a real mocking framework would be able to provide specific responses for specific parameter inputs.    I’ll leave correcting this problem as an exercise to the reader.  Smile )

So now, when we exercise this class, it will actually return stuff that you tell it to:

This code:

WriteLn('IActuallyUseful with ISimpleMock');
SimpleMock := TSimpleMock<IActuallyUseful>.Create;
SimpleMock.AddExpectation('Multiply', 99);
SimpleMock.AddExpectation('ReverseString', 'This is actually working');
WriteLn(SimpleMock.InterfaceToCall.Multiply(6, 7));
WriteLn(SimpleMock.InterfaceToCall.ReverseString('This does not matter'));
WriteLn;

has the following output:

image

Note that the responses are not what you think they would be based on the parameters (you think that 6 times 7 would return 42…), but what you told them to be in the AddExpectation call.

Now, you can use ISimpleMock<T> to provide specific feedback for a given method call.  Maybe you have an interface method which returns a Boolean value that you want to test. You can use ISimpleMock<IBooleanMethod> to test what happens when the method returns True as well as when that method returns False

Conclusion

Okay, so there you have it:  A useful implementation of TVirtualInterface.  Though the above examples are really simple, they can actually be used in real world testing – particularly the ISimpleStub<T> implementation. Stubbing is common in unit testing, and even though it is a very basic implementation, it can be used to stub out any interface.

None of this is useful if you know what interface you need and how you are going to implement it.  But there are cases when you don’t know what interface you will need for a particular problem, and you need to be able to flex to whatever interface the situation calls for.  Mocking and stubbing are perfect examples.  That’s a powerful and useful thing to be able to do.  Hopefully this little series has helped you see that.

TVirtualInterface: Next Steps

By Nick at June 14, 2012 06:48
Filed Under: Delphi, Software Development

Okay, so my last article was pretty fun – you got a look at TVirtualInterface and how you can use it to implement any interface.  Now, I want to be clear – the code in that article was demo code.  That is, it was purely for illustrative purposes.  I can’t think of any reason why you’d actually, in the real world, implement an interface that way. But after reading it, you should be able to see how TVirtualInterface works and how you can get it to do what you want. 

Now, in that article I promised you that my next blog post on the topic would be an example of using TVirtualInterface in a more useful manner.  But I guess I lied, because this blog post is about how you can create a slightly better version of TVirtualInterface.

So a while back, I wrote a post about getting you to “think generically” and how generics (or as I prefer to think of them, parameterized types) are useful in more ways than just collections and lists.   Well, I got to looking at TVirtualInterface and I thought, “You know, here’s a class that actually requires type information about a given type, and in order for it to do anything useful, you have to give it a type in the constructor, so hmmm…….”.  And you can guess where I went from there. 

So, consider the following class declaration:

type

  TVirtualInterfaceEx<T: IInvokable> = class(TVirtualInterface)
  protected
    procedure DoInvoke(Method: TRttiMethod;  const Args: TArray<TValue>; out Result: TValue);
    procedure DoInvokeImpl(Method: TRttiMethod;  const Args: TArray<TValue>; out Result: TValue); virtual; abstract;
  public
    constructor Create;
  end;

This is a pretty simple descendent for TVirtualInterface.  The most obvious thing is that it takes a parameterized type T which is constrained to be an interface descending from IInvokable.  That enables you to explicitly declare what interface TVirtualInterfaceEx is going to implement.  You should notice, too that TVirtualInterfaceEx is an abstract class, as the DoInvokeImpl method is abstract.

So, once you have the parameterized type, you know everything you need to implement the interface.  As you know from the previous article, the thing you need to do is to provide an implementation of DoInvoke.  So TVirtualInterfaceEx employs the technique I’ve described before whereby you implement the interface in the base class and provide a “real” implementation in a separate method invoked by the base class.  So, the implementation looks like this:

constructor TVirtualInterfaceEx<T>.Create;
begin
  inherited Create(TypeInfo(T), DoInvoke);
end;

procedure TVirtualInterfaceEx<T>.DoInvoke(Method: TRttiMethod;  const Args: TArray<TValue>; out Result: TValue);
begin
  DoInvokeImpl(Method, Args, Result);
end;

The constructor is pretty simple – it is parameter-less and  calls a sibling constructor, passing in the TypeIinfo for your interface and the DoInvoke method which is of type TVirtualInterfaceInvokeEvent.  The code for DoInvoke method simply calls the DoInvokeImpl method, which, because it is abstract, descendent classes must override.

Thus, to use this class, all you need to do is to descend from it and provide an interface as a parameterized type and an implementation for DoInvokeImpl.   So, if we wanted to implement the IActuallyUseful interface from the previous example, all we need to do is:

  TActuallyUsefulEx = class(TVirtualInterfaceEx<IActuallyUseful>)
  protected
    procedure DoInvokeImpl(Method: TRttiMethod;  const Args: TArray<TValue>; out Result: TValue); override;
  end;

implementing DoInvokeImpl with the same code that was in the DoInvoke event of the TActuallyUseful class. 

By the way, I should mention that the code for these demos on TVirtualInterface, including a sneak peek at the code for the next article, is available as part of my demo code project on BitBucket.

This isn’t anything really fancy, but I liked it because it simplified the process of creating virtual interface implementations and provided another example of a good use for parameterized types.  I also like what I mentioned previously, that it clearly declares what interface it is implementing.

Anyway, I thought it was a cool little wrapper/descendent for the TVirtualInterface class.  And I promise that the next blog post on this stuff will show an example of using it in a truly dynamic way.

TVirtualInterface: Interfaces without an Implementing Class

By Nick at June 10, 2012 14:37
Filed Under: Delphi, Software Development

I would be really disappointed if we spent an hour discussing software development and I didn’t at least once say to you "Program against interfaces, not against implementations".  It’s sort of a mantra for me – a way of life if you will.  It’s a bedrock principle of development as far as I’m concerned. Programing against interfaces and not against implementations is the only way to truly decouple your code.  And if you don’t believe that decoupling your code is important, I’d like you to stop reading right now, get a small ball-peen hammer, and keep hitting yourself in the forehead until you change your mind.

So if you’ve made it this far, you’ll know that implementing interfaces is needed to use them.  You have to put some code behind an interface to make it do anything.  Normally, this is done with an implementing class:

type
  ISprocketProcessor = interface
    procedure ProcessSprockets;
  end;

  TSprocketProcessor = class(TInterfacedObject, ISprocketProcessor)
    procedure ProcessSprockets;
  end;

But what if you could implement an interface without having a specific class?  What if there were a way to implement any interface with a single module of code? What if you could decide at runtime how to implement an interface?  Would I even be asking these questions and writing this if those things weren’t possible?

So, yes, obviously it is.  Delphi XE2 introduces a very cool new class called TVirtualInterface. Its purpose is to allow you to descend from it and respond to any interface dynamically.  If you think about that for a second you’ll realize that this is pretty powerful. For instance, it’s the thing that lets the awesome Delphi Mocks Framework provide a mock implementation of any interface that you pass to it.

Generally, when you implement an interface, you provide a class that implements it in a specific way – i.e. that implementation becomes static at runtime. There are ways – typically via Dependency Injection – that allow you to choose an implementation, but even then you are limited to a specific set of implementations.   TVirtualInterface allows you to dynamically -- i.e. at runtime – determine how an interface will be implemented.  The examples in this article will show a fixed way to implement TVirtualInterface so you can get the basics of how to use TVirtualInterface.  In a future article, we’ll look at more dynamic ways to use this sweet class.

Here’s the public interface for TVirtualInterface:

  { TVirtualInterface: Creates an implementation of an interface at runtime.
    All methods in the Interface are marshaled through a generic stub function
    that raises the OnInvoke event.}
  TVirtualInterface = class(TInterfacedObject, IInterface)
 ...
  public
    function QueryInterface(const IID: TGUID; out Obj): HResult; virtual; stdcall;
    { Create an instance of TVirtualInterface that implements the methods of
      an interface.  PIID is the PTypeInfo for the Interface that is to be
      implemented. The Interface must have TypeInfo ($M+). Either inherit from
      IInvokable, or enable TypeInfo for the interface. Because this is an
      TInterfacedObject, it is reference counted and it should not be Freed directly.
      }
    constructor Create(PIID: PTypeInfo); overload;
    constructor Create(PIID: PTypeInfo; InvokeEvent: TVirtualInterfaceInvokeEvent); overload;
    destructor Destroy; override;
    { OnInvoke: Event raised when a method of the implemented interface is called.
      Assign a OnInvoke handler to perform some action on invoked methods.}
    property OnInvoke: TVirtualInterfaceInvokeEvent read FOnInvoke write FOnInvoke;
  end;

First, you should notice that TVirtualInterface descends from TInterfacedObject and implements IInterface.  The three methods of IInterface are implemented to allow the class to be properly reference counted like any other interface-implementing class.  Second, the interface that you want to implement with it needs to have TypeInfo enabled for it.  The easiest way to make that happen is to descend your interface from IInvokable.  Otherwise, you’ll need to use the {$M+} switch for your interface. Notice, too, that the comment above the class declaration says what I said early – using TVirtualInterface will let you, well, do anything you want with an interface at runtime.  Cool. 

So, in order to actually make TVirtualInterface do something, you need to create a descendent class and provide two things:  a constructor and an implementation of the DoEvent method.

Here’s an TVirtualInterface descendent that is as simple an example as I could think of:

type
  TSimplestVirtualInterface = class(TVirtualInterface)
    constructor Create(PIID: PTypeInfo);
    procedure DoInvoke(Method: TRttiMethod;  const Args: TArray<TValue>; out Result: TValue);
  end;

constructor TSimplestVirtualInterface.Create(PIID: PTypeInfo);
begin
  inherited Create(PIID, DoInvoke);
end;

procedure TSimplestVirtualInterface.DoInvoke(Method: TRttiMethod;
  const Args: TArray<TValue>; out Result: TValue);
begin
  WriteLn('You called a method on an interface');
end;

The only thing this will do is to write out to the console – no matter what.  You can pretend it implements any interface, and no matter what you call on that interface, it will merely write to the console. 

The constructor takes a single parameter, PIID, which is is the TypeInfo for the interface you want to “implement”.  (That’s why the interface in question must have the {M+} switch – usually via IInvokable.)  Inside the constructor, a call to a different constructor is made.  The PIID parameter is passed in, as is a reference to DoInvoke, which is a method that matches the type TVirtualInterfaceInvokeEvent.  Thus, the constructor is basically saying “Here is the type of information for the interface I’m implementing, and the method you should run whenever a method is called on that interface.”

In our case, the DoInvoke method only does one thing no matter what – writes to the console.

So, for instance, say you declare an interface:

type
  IGoStop = interface(IInvokable)
  ['{3B2171B0-D1C3-4A8C-B09E-ACAC4D625E57}']
    procedure Go;
    procedure Stop(aInteger: integer);
  end;

And then you run the following code in a console application:

   GoStop := TSimplestVirtualInterface.Create(TypeInfo(IGoStop)) as IGoStop;
   GoStop.Go;
   GoStop.Stop(42);

the console output will look like this:

image

 

You see the output twice because the code called two methods.  It doesn’t matter what you call – that output will happen no matter what.  It doesn’t matter what interface you pass in or what method you call, the result will be the same.

But of course that isn’t useful – to be of any use, you need to be able to know what is getting called, what is getting passed in, and respond accordingly.

Well, you can do that, because if you look at the signature of the DoInvoke method, you’ll note that when it gets called by the TVirtualInterface.OnInvoke event, it gets passed the RTTI for the method that was called, an array of TValue that contain the interface itself and all the arguments that the method was passed, as well as an out parameter of type TValue that allows you to return a value if the method being called is a function. 

So how about we simply use the DoInvoke event to report out what all that information that it receives.

procedure TReportingVirtualInterface.DoInvoke(Method: TRttiMethod;
  const Args: TArray<TValue>; out Result: TValue);
var
  Arg: TValue;
  ArgType, ArgName: string;
  TempKind: TTypeKind;
begin
  Write('You called the ', Method.Name, ' method ');
  if Length(Args) > 1 then
  begin
    Writeln('and it has ', Length(Args) - 1,' parameters:');
    for Arg in Args do
    begin
      TempKind := Arg.Kind;
      if TempKind <> tkInterface then
      begin
        ArgName := Arg.ToString;
        ArgType := Arg.TypeInfo.Name;
        Writeln(ArgName, ' which is of the type ', ArgType);
      end;
    end;
  end else
  begin
    Writeln(' and it has no parameters.');
  end;
end;

This code simply looks over and reports out about the Method and Args parameters that get passed in when the interface is invoked.  The very first item in the array is always type information about the interface itself, and the rest are the parameters, in order, as they were passed in.  Here, the code simply reports out their values and types, but of course, you can process them as you please. 

Again, that is interesting information, but it’s just a step towards understanding how TVirtualInferface works.  Let’s create something that actually does what we want it to.

Here’s a basic interface:

type
  IActuallyUseful = interface
  ['{16F01BF0-961F-4461-AEBE-B1ACB8D3F0F4}']
    procedure SayHello;
    function ReverseString(aString: string): string;
    function Multiply(x, y: integer): integer;
  end;

Then, below is the DoInvoke method for a TActuallyUseful class that will actually do what the interface purports to do:

procedure TActuallyUseful.DoInvoke(Method: TRttiMethod;
  const Args: TArray<TValue>; out Result: TValue);
begin
  if UpperCase(Method.Name) = 'SAYHELLO' then
  begin
    WriteLn('Hello World!');
  end else
  begin
    if UpperCase(Method.Name) = 'REVERSESTRING' then
    begin
      Result := ReverseString(Args[1].AsString)
    end else
    begin
      if UpperCase(Method.Name) = 'MULTIPLY' then
      begin
          Result := Args[1].AsInteger * Args[2].AsInteger;
      end else
      begin
        raise Exception.Create('Bad Parameter name was passed in to the DoInvoke method');
      end;
    end;
  end;
end;

This code should be fairly self-explanatory.  It simply checks for the name of the method that was called, and then executes code using the parameter information passed in the Args parameter.  If the call is a function, the Result parameter is used to return a value.   

You should  remember that the initial item in the Args array (that is, the one at the “zero-eth” position) is the interface type itself.  The code also makes assumptions about the number and types of the parameters.  Since the code can only be invoked by the methods declared on IActuallyUseful interface, the code can make safe assumptions about the types and order of the parameters.

Now all of this code above is fairly straight-forward – we are basically simulating an implementing class in our examples.  Nothing is truly dynamic.  The code here merely shows simple examples of how TVirtualInterface works in a fairly static way. You should now be able to see how you could dynamically implement an interface using a TVirtualInterface descendent.

Coding against interfaces is critical for writing good, clean code.  TVirtualInterface is just another powerful tool in your toolbox for doing just that.

Fun Code of the Week #4

By Nick at June 08, 2012 15:14
Filed Under: Delphi, Fun Code

Adapted from my answer on StackOverflow:

function RemoveChars(const aString: string; aCharsToRemove: TSysCharSet): string;
var
  C: Char;
begin
  Result := '';
  for C in aString do
  begin
    if not CharInSet(C, aCharsToRemove) then
    begin
      Result := Result + C;
    end;
  end;
end;

My Book

A Pithy Quote for You

"When things go wrong in your command, start searching for the reason in increasingly larger concentric circles around your own desk."    –  General Bruce C. Clarke

Amazon Gift Cards

General Disclaimer

The views I express here are entirely my own and not necessarily those of any other rational person or organization.  However, I strongly recommend that you agree with pretty much everything I say because, well, I'm right.  Most of the time. Except when I'm not, in which case, you shouldn't agree with me.

Month List