Monday, November 30, 2015

Runtime Narrow Interfaces in Dart


My memento has a wide interface. I continue to work with the memento pattern in Dart. The initial implementation went well, but the devil is in the details.

The details in this case come in the form of implementation item #1 from the Gang of Four book, which suggest that only the originator class should have access to the properties of the memento object. As I found last night, that is not an easy thing to do in Dart. There is no concept of friend classes in Dart. There is not even an easy way to obtain the caller of a function to determine access.

In the end, I hacked a caller into the memento object in my example code by examining the stacktrace of a thrown exception. There is no world in which that is a good idea, so tonight, I try to do a little better. Since neither the requirements nor the limitations have changed, I have to try an alternate approach. And I think it all has to be done at runtime.

The originator class in my example is the VeletFogMachine, which plays various songs from the late, great Mel Tormé. The memento class is Playing, which the caretaker context can use to replay previous songs. Again, the caretaker should not be able to access any song information—only supply the Playing memento to the originator so that it can be handled properly.

What I come up with is a runtime secret, supplied to by the VelvetFogMachine:
class Playing {
  Song _song;
  double _time;
  double _secret;

  // Narrow interface for the world
  Playing();

  // Wide interface for the VelvetFogMachine
  Playing.forTheVelvetFogMachine(this._song, this._time, this._secret);
  // ...
}
This named constructor suggests that it only works with the VelvetFogMachine. In reality, it is possible to use it from outside that context, but it ought to feel really strange to just about anyone.

The secret supplied to the constructor can then be used to check access to a particular method, like the secretSong() method:
class Playing {
  // ...
  Song secretSong(double secret) {
    // Runtime check for access
    _checkAccess(secret, #secretSong);
    return _song;
  }
  // ...

  _checkAccess(secret, memberName) {
    if (secret == _secret) return;

    throw new NoSuchMethodError(this, memberName, [secret], {});
  }
}
The secret itself has to come from the VelvetFogMachine originator class and it has to be private to that class so that no other classes can get access:
import 'dart:math';
final rand = new Random(1);

// The "Originator"
class VelvetFogMachine {
  Song currentSong;
  double currentTime;
  final double _secret = rand.nextDouble();
  // ...

  // Create a memento of the current state
  Playing get nowPlaying {
    // Simulate playing at some time later:
    var time = 5*rand.nextDouble();

    return new Playing.forTheVelvetFogMachine(currentSong, time, _secret);
  }
  // ...
}
That works. The original code continues to function properly when used inside the originator:
class VelvetFogMachine {
  // ...
  void backTo(Playing p) {
    print("  *** Whoa! This was a good one, let's hear it again :) ***");
    _play(p.secretSong(_secret), p.secretTime(_secret));
  }
}
Furthermore, the caretaker code is unable to access the secretSong() method:
List<Playing> replayer = [];

  var scatMan = new VelvetFogMachine();
  // ...

  scatMan.play(
      'New York, New York Medley',
      'A Vintage Year'
  );
  replayer.add(scatMan.nowPlaying);
  // ...

  // This should not work:
  try {
    print("Caretaker says last remembered song is: ${replayer.last.secretSong(0.0)}");
  }
  on NoSuchMethodError {
    print("Yay! Caretaker was denied access to the memento song.");
  }
This results in the NoSuchMethodError output:
$ ./bin/play_melvie.dart                                       
...
Playing New York, New York Medley // A Vintage Year @ 0.00
Playing The Lady is a Tramp // The Velvet Frog: The Very Best of Mel Tormé @ 0.00
  *** Whoa! This was a good one, let's hear it again :) ***
Playing New York, New York Medley // A Vintage Year @ 4.60

Yay! Caretaker was denied access to the memento song.
So this works, but it is an awful lot of work and there are still ways around it. Still, unless someone has a suggestion, I will likely stick with this as the best approach to narrowing the interface of the memento when discussing in Design Patterns in Dart.

Play with this code on DartPad: https://dartpad.dartlang.org/a1971dcad8f0466d7cfe


Day #19

Sunday, November 29, 2015

Making Friends in Dart


The memento in my memento pattern is a tad friendly. In the original Gang of Four book, the suggested implementation has a narrow interface into the memento class. That is, only the originator of the memento can access the memento's properties.

My Dart version is considerably more open:
// The Memento
class Playing {
  Song song;
  double time;
  Playing(this.song, this.time);
}
I continue to work on the VelvetFogMachine application. It needs access to the auto-defined song and time getter methods when restoring a previously playing Mel Tormé song:
// The "Originator"
class VelvetFogMachine {
  // ..
  // Restore from memento
  void backTo(Playing p) {
    print("  *** Whoa! This was a good one, let's hear it again :) ***");
    _play(p.song, p.time);
  }
}
Really, all that the originator needs to access are the getters as shown. I do not need the auto-defined setters. I could address this with private properties paired with explicit, public getters:
class Playing {
  Song _song;
  double _time;
  Playing(this._song, this._time);

  Song get song => _song;
  double get time => _time;
}
This helps a little to address concerns with encapsulation. It is still possible for the caretaker context, which should only play or restore songs (set / restore state), to access the song and time properties. In most cases, this will not be a problem. The caretaker will merrily play and restore without ever wondering about the memento returned by nowPlaying:
  scatMan.play(
      'New York, New York Medley',
      'A Vintage Year'
  );
  replayer.add(scatMan.nowPlaying);
  //  Play other songs...

  // The New York, New York Medley with George Shearing really is wonderful
  scatMan.backTo(replayer.last);
That said, there is virtue in narrowing the interface. Another coder might come along and attempt to get access the memento song title. To achieve that, encapsulation would need to be broken, violating the very intention of the memento pattern.

So what is to be done here? Unfortunately, I cannot think of much in Dart where there is no support for friend classes (as far as I know). The best I can come up with is an ugly hack to determine the caller of a noSuchMethod() invocation.

In Dart, if a method is not found, but the class declares a noSuchMethod(), then that noSuchMethod() method is invoked. I could rewrite the public getters for song and time as:
class Playing {
  Song _song;
  double _time;
  Playing(this._song, this._time);

  noSuchMethod(Invocation i) {
    if (i.memberName == #song) return this._song;
    if (i.memberName == #time) return this._time;

    return super.noSuchMethod(i);
  }
}
That is fairly straight-forward. If the noSuchMethod() method is invoked with song as the method name, then the private _song property is returned. The same thing happens with time. If something else if invoked, then the superclass noSuchMethod() is invoked, likely throwing a halting exception.

This does nothing to prevent classes other than VelvetFogMachine from accessing song and time. For that, I need access to the class that invoked the getter. As far as I know there is no "real" way to accomplish this in Dart. The best I can do is throw an exception and catch the stacktrace:
class Playing {
  Song _song;
  double _time;
  Playing(this._song, this._time);

  noSuchMethod(Invocation i) {
    try { throw new Error(); }
    catch (_exception, stackTrace) {
      if (!stackTrace.toString().contains(new RegExp(r'\#1\s+VelvetFogMachine'))) {
        return super.noSuchMethod(i);
      }
    }

    if (i.memberName == #song) return this._song;
    if (i.memberName == #time) return this._time;

    return super.noSuchMethod(i);
  }
}
That works and dartanalyzer doesn't complain (with a @proxy annotation applied to the class). But yuck. Further, I an unsure if this works in all Dart VMs (it does not work on DartPad, for instance).

So, unless someone has any ideas, it seems safe to say that Dart classes are friendly to everyone. In other words, Dart classes are slightly too friendly for the memento pattern.


Day #18

Saturday, November 28, 2015

Memento Not As State


I really need to cut out the extreme late night coding. I left off last night with a fully formed planned to increase the "Dartiness" in my memento pattern example, but in the light of day I haven't the velvet foggiest notion what that plan might have been. No pity here though, there is still something to say about the existing code.

I am curious about the relationship between the internal state of the originator and the memento object. In particular, should the memento object be the state in the originator class? After last night, that is exactly what the VelvetFogMachine originator class does in its play() method:
// The "Originator"
class VelvetFogMachine {
  // The Memento
  Playing _nowPlaying;

  // Set the state
  void play(String title, String album, [double time = 0.0]) {
    print("Playing $title // $album @ ${time.toStringAsFixed(2)}");
    _nowPlaying = new Playing(title, album, time);
  }
  // ...
}
The second time around with the code, I think perhaps the memento-as-state is inappropriate. Oh, it works—especially in this short example. In real life code however, it is more likely that the VelvetFogMachine would want to track the current song and current time directly. Something along the lines of the following achieves a nearness to a more organic VelvetFogMachine:
class VelvetFogMachine {
  Song currentSong;
  double currentTime;

  void play(String title, String album, [double time = 0.0]) {
    currentSong = new Song(title, album);
    currentTime = time;
    print("Playing $currentSong @ ${time.toStringAsFixed(2)}");
  }
  // ...
}
My romance of a better example would push the song title and album into a new Song class:
class Song {
  String title, album;
  Song(this.title, this.album);
  String toString() => "$title // $album";
}
Ah, Dart code, do I love you because you're beautiful? You certainly know my heart, but I still do not believe that is the "Dartiness" I was planning last night. Hopefully I can figure it out because it's really under my skin.

Back to my example, the currentSong and currentTime feel like properties that could exist before realizing that a memento pattern was needed. In other words, I think this is a stronger memento example. Now what to do with the memento class? Previously, it stored separate song title, album and time properties:
class Playing {
  String title, album;
  double time;
  Playing(this.title, this.album, this.time);
}
I am tempted to stick with with this structure in the memento class. After all, it mirrors the signature of the play() method in the VelvetFogMachine's play() method that creates the internal state being memento-ized. In the end, I think it best for the memento class to mirror the internal structure of the originator class, so title and album are replaced with song:
class Playing {
  Song song;
  double time;
  Playing(this.song, this.time);
}
Now that I have settled on this for the Playing memento, the method that creates the memento in VelvetFogMachine is trivial. The nowPlaying getter method simply instantiates the memento with the current song and time:
class VelvetFogMachine {
  // ...
  Playing get nowPlaying => new Playing(currentSong, currentTime);
  // ...
}
Everyday's a holiday with Dart and hash-rocket return methods. That's good, clean fun.

But what of the method that restores state from a previously recorded memento? It now has to translate the Song-based memento into the three argument play() method:
class VelvetFogMachine {
  // ...
  void backTo(Playing p) {
    print("  *** Whoa! This was a good one, let's hear it again :) ***");
    play(p.song.title, p.song.album, p.time);
  }
}
Some indirection aside, that is not too horrible. Certainly it is better that the VelvetFogMachine be responsible for translating a memento of previous state into a play() instead of the caretaker context. The whole point of the memento after all, is to prevent exposing internal implementation details when saving state.

If the indirection bothers me, I can replace the current play() with a call to a private, Song-based method:
  void play(String title, String album, [double time = 0.0]) {
    _play(new Song(title, album), time);
  }

  void _play(Song s, double t) {
    currentSong = s;
    currentTime = t;
    print("Playing $currentSong @ ${currentTime.toStringAsFixed(2)}");
  }
With that, the restore-from-memento method can invoke the same _play() method:
  void backTo(Playing p) {
    print("  *** Whoa! This was a good one, let's hear it again :) ***");
    _play(p.song, p.time);
  }
I think I prefer that approach. That said, I might stick with the previous, non-private-based play() method in the book. The difference between the three argument play() method and the two-property memento better illuminates the need to hide implementation details of the originator from the outside world.

That's about all for this bit of exploration. I am clearer on the need for the memento to encapsulate, but not be, the internal state of the originator. I had been glossing over that in my mind, but am happy for having cracked that chestnut.

And I do think I remember that "Dartiness" factor I had hoped to explore. Hopefully we are not strangers in the late night and I will still remember it tomorrow. Stay tuned Mel fans!

Play with this code on DartPad: https://dartpad.dartlang.org/35e0056a1f290c74d996

Day #17

Friday, November 27, 2015

A Better Memento Example: Now with More Encapsulation!


Up tonight, I take a closer look at encapsulation in the memento pattern. I have a decent start on the pattern from last night, but I glossed over one of the important reasons behind the memento pattern. Per the Gang of Four book, the pattern is applicable when obtaining state would break encapsulation.

Currently, the caretaker of the pattern plays a song, remembers the state on occasion, and replays particularly good Mel Tormé songs:
  List<String> replayer = [];
  var scatMan = new VelvetFogMachine();
  // ...
  scatMan.play(
      'New York, New York Medley',
      'A Vintage Year'
  );
  replayer.add(scatMan.nowPlaying);
  // ...

  // The New York, New York Medley with George Shearing really is wonderful
  scatMan.backTo(replayer[1]);
The encapsulation in this case is in the nowPlaying getter of the VelvetFogMachine. The nowPlaying property in the Melvie-tastic VelvetFogMachine is a list of strings (the title and album of the song):
class VelvetFogMachine {
  List<String> _nowPlaying;
  // ...
}
There is not much to the state being exposed and what state is exposed comes directly from the caretaker (i.e. the title and album). So this may not be the ideal example. In addition to the song playing, I will try storing the current time within the song as well:
// The Memento
class Playing {
  String title, album;
  double time;
  Playing(this.title, this.album, this.time);
}
If I tried to store this in the caretaker context, then I would certainly be breaking encapsulation. I would have to note the title, album and time at which the playing moved to the next song. Those aren't exactly related values, so this seems a better example.

Since I do not wish to expose the underlying implementation, the replayer can no longer be a list of strings. Instead, it needs to be a list of Playing objects (i.e. a list of mementos):
  List<Playing> replayer = [];
Nothing else needs to change in the caretaker code. The scatMan still plays songs by title and album. The nowPlaying property still returns a memento—albeit a more complex one. The backTo() method still takes the memento and uses it to restore state. Nothing really changed, but the more complex example better justifies the application of the pattern.

The code in VeletFogMachine does not change much—it just needs to accommodate time now. The play() method optionally accepts it:
  void play(String title, String album, [double time = 0.0]) {
    print("Playing $title // $album @ ${time.toStringAsFixed(2)}");
    _nowPlaying = new Playing(title, album, time);
  }
And the backTo() method needs to use the stored value to resume playing where it left off:
  // Restore from memento
  void backTo(Playing memento) {
    print("  *** Whoa! This was a good one, let's hear it again :) ***");
    play(memento.title, memento.album, memento.time);
  }
After adding a random number for the saved time, I have everything working—including restoring from the slightly more complex state:
$ ./bin/play_melvie.dart                                       
...
Playing The Lady is a Tramp // The Velvet Frog: The Very Best of Mel Tormé @ 0.00
  *** Whoa! This was a good one, let's hear it again :) ***
Playing New York, New York Medley // A Vintage Year @ 1.28
That seems a good place to stop for tonight. The memento seems a relatively simple pattern, which is making me feel the urge to move on to other patterns. But it is probably worth exploring a few more facets of the pattern in the next day or so. First up, I plan to see if there is a more "Darty" solution. Tomorrow.

Play with this code on DartPad: https://dartpad.dartlang.org/bf9c7454247a122030f9


Day #16

Thursday, November 26, 2015

The Velvet Fog Memento


I'm picking patterns to explore for Design Patterns in Dart by throwing proverbial darts at whatever design pattern book happens to be closest at hand. Up tonight is the memento.

I don't much care for the abstract nature of the examples in the Wikipedia article on memento. The constraint solver example in the GoF book always seemed too academic to me (though I recognize the importance of constraint solvers). I would prefer an example to which everyone can relate. Maybe something like a machine dedicated to building the ultimate Mel Tormé playlist. Everybody can relate to Melvie.

The "originator" in this scenario will be the VelvetFogMachine. It will be responsible for playing the best of the most gifted scatman of the 20th century. For this first pass, I will forgo the usual method names in the memento pattern (e.g. `CreateMemento`, `restoreFromMemento`). Instead, I would like to explore with more natural names like play(), backTo(), and nowPlaying:
// The "Originator"
class VelvetFogMachine {
  // Set the state
  void play(String title, String album);

  // Return a memento for possible later restoration
  Memento get nowPlaying;

  // Restore from memento
  void backTo(Memento memento);
}
The nowPlaying method will return a memento object that can be used to restore the currently playing song (i.e. the state) at a later time with backTo().

I will worry about proper serialization another day. For now, I make the Memento object as simple as possible. It encapsulates a string representation of the state:
class Memento {
  String state;
  Memento(this.state);
}
Back in the VelvetFogMachine originator, the play() method prints the currently playing song and stores the internal state:
class VelvetFogMachine {
  List<String> _nowPlaying;

  void play(String title, String album) {
    print("Playing $title // $album");
    _nowPlaying = [title, album];
  }
  // ...
}
As for generating a memento, I join the song and album with triple-colons in a string:
Memento get nowPlaying => new Memento(_nowPlaying.join(':::'));
Similarly, going back to a previous state needs to split the triple-colons and change the VelvetFogMachine with its own call to play():
  void backTo(Memento memento) {
    print("  *** Whoa! This was a good one, let's hear it again :) ***");
    var previous = memento.state.split(':::');
    play(previous[0], previous[1]);
  }
That more-or-less covers the functionality of the originator (VelvetFogMachine) and memento (Memento) in the pattern. All that is left is the caretakers. For this first pass, I put the caretaker back in the main() entry point.

Here, I need a list of possible replay targets and an instance of the VelvetFogMachine to play that scat music, save my place on occasion, and replay the very best moments:
main() {
  List replayer = [];

  var scatter = new VelvetFogMachine();
  scatter.play(
      'Blue Moon',
      'The Velvet Frog: The Very Best of Mel Tormé'
  );
  scatter.play(
      '\'Round Midnight',
      'Tormé'
  );
  replayer.add(scatter.nowPlaying);

  scatter.play(
      'It Don\'t Mean A Thing (If It Ain\'t Got That Swing)',
      'Best Of/ 20th Century'
  );
  scatter.play(
      'New York, New York Medley',
      'A Vintage Year'
  );
  replayer.add(scatter.nowPlaying);

  scatter.play(
      'The Lady is a Tramp',
      'The Velvet Frog: The Very Best of Mel Tormé'
  );

  // The New York, New York Medley with George Shearing really is wonderful
  scatter.backTo(replayer[1]);
}
And that does it. I can play some wonderful tunes and, when one really strikes me, I can replay it later thanks to a memento:
$ ./bin/play_melvie.dart
Playing Blue Moon // The Velvet Frog: The Very Best of Mel Tormé
Playing 'Round Midnight // Tormé
Playing It Don't Mean A Thing (If It Ain't Got That Swing) // Best Of/ 20th Century
Playing New York, New York Medley // A Vintage Year
Playing The Lady is a Tramp //  The Velvet Frog: The Very Best of Mel Tormé
  *** Whoa! This was a good one, let's hear it again :) ***
Playing New York, New York Medley // A Vintage Year
I do not know that there is much more to explore in this pattern. Where to serialize should be addressed (maybe in the Memento?). I have more general questions about how to present this—I am not fond of UML and prefer real-world examples over abstract ones. Still, I ought to be able to present how this generalizes for usage elsewhere—it is a pattern after all. Last, I need to see if I can find ways in which the pattern can be "Dartier." But for now, this is a fine stopping place.

Play with this code on DartPad: https://dartpad.dartlang.org/5ea65d5b9e6791462547


Day #15

Wednesday, November 25, 2015

Testing Patterns


Tonight, I start testing the code in Design Patterns in Dart. I expect my testing approach will evolve as the book is written. For now, I plan to test code used directly in the book (for obvious reasons) and some of the experimental code that I use to explore patterns before writing.

To start, I will write some tests for the Flyweight pattern coffee shop example with which I have been playing. I start by adding the test packages to the list of development dependencies in my pubspec.yaml:
name: flyweight_code
dependencies:
  reflectable: any
dev_dependencies:
  test: any
transformers:
- reflectable:
    entry_points:
      - bin/coffee_orders.dart
    formatted: true
After a pub get, I start a test/coffee_shop_test.dart file:
library coffee_shop_test;

import 'package:test/test.dart';

import 'package:flyweight_code/coffee_shop.dart';

main(){
  // Tests will go here...
}
With that, I can define some test setUp() to create my flyweight-based coffee shop and place some coffee orders:
  var shop;
  setUp((){
    shop = new CoffeeShop()
      ..order('Cappuccino', 'large', who: 'Fred', fooFoo: 'Extra Shot')
      ..order('Espresso',   'small', who: 'Bob')
      ..order('Cappuccino',     'large', who: 'Alice');
  });
I can test some of the properties of this coffee shop:
  test('it can calculate profit', (){
    expect(shop.profit, 15.2);
  });
  test('it flyweights', (){
    expect(CoffeeFlavor.totalCount, 2);
  });
The profit is based on the cost per ounce of the different coffees. The total count of coffee flavors is determined from the number of flyweight objects in use. Those are both fairly easy tests and do not take much effort to get working. Testing in Dart is still quite pleasant.

I am curious about testing print() statements. I have not had an excuse to do so in any of my Dart code to date, but I happen to use print statements in the serve() method of the coffee shop:
  void serve() {
    _orders.forEach((o) { print("Served ${o.service}.");});
  }
The service property for the orders is something like "Espresso to Bob", so I want to verify that serving drinks prints out the phrase "Served Espresso to Bob". Since there are a number of print() statements throughout the code, I need to verify that all prints contain this phrase. In test parlance, this is expressed as:
  test('prints when serving', (){
    expect(shop.serve, prints(contains('Served Espresso to Bob.')));
  });
So that turns out to be pretty easy! More importantly, the tests all pass:
$ pub run test -r expanded
00:00 +0: test/coffee_shop_test.dart: it can calculate profit
00:00 +1: test/coffee_shop_test.dart: it flyweights
00:00 +2: test/coffee_shop_test.dart: prints when serving
00:00 +3: All tests passed!
So I can test an individual patterns. Now I need to test all of them in the repository. As far as I know, this is the purview of Bash scripts. Fortunately, I have done this before:
#!/bin/bash -e

shopt -s extglob

for X in !(LICENSE|README.md|bin|packages)
do
    # Change the current working directory to pattern directory
    cd $X
    echo "[TEST] $X "

    # Update pub
    echo -n "pub update"
    pub get >/dev/null
    echo " (done)"

    # Run the actual tests
    pub run test
    echo

    # Back to the top-level directory
    cd - >/dev/null
done
This iterates over all files and directories in the repository, except for LICENSE, README.md, bin, and packages. In each code directory, it runs the tests. With that, I have a build script for my book code:
$ ./bin/test.sh
[TEST] flyweight 
pub update (done)
00:00 +3: All tests passed!
I think that I am done now with the Flyweight pattern. I may make a quick check of things tomorrow, but I am likely on to a new pattern.

Day #14


Tuesday, November 24, 2015

Reflectable Subtypes and the Flyweights that Love Them


Tonight, I continue my exploration of the Reflectable package as applied to the Flyweight Pattern.

I am quite happy with the current state of the Reflectable-based code. I have defined a flavor constant that inherits from Reflectable so that it can annotate my code:
class Flavor extends Reflectable {
  const Flavor()
    : super(newInstanceCapability);
}
const flavor = const Flavor();
I then use this constant to mark the individual concrete flyweight objects—in the case of this example, coffee flavors for my coffee shop:
@flavor
class Cappuccino implements CoffeeFlavor {
  String get name => 'Cappuccino';
  double get profitPerOunce => 0.35;
}

@flavor
class Espresso implements CoffeeFlavor {
  String get name => 'Espresso';
  double get profitPerOunce => 0.15;
}
It seems a bit of a nuisance to have to annotate every concrete flyweight class like this. Thanks to a pointer from Erik Ernst in yesterday's comments, I can eliminate that nuisance.

Reflectable works by only applying a limited subset of built-in dart:mirrors capabilities. Currently, I only use newInstanceCapability so that the CoffeeFlavor factory constructor can create new instances of the concrete flyweight objects:
class CoffeeFlavor {
  // ...
  factory CoffeeFlavor(name) {
    return _cache.putIfAbsent(name, () =>
        classMirrors[name].newInstance('', []));
  }
  // ...
}
Reflectable objects like my flavor constant come with the built-in ability to find all classes annotated by the object, so the classMirrors map is easily assembled from flavor:
class CoffeeFlavor {
  // ...
  static Map classMirrors = flavor.
    annotatedClasses.
    fold({}, (memo, c) => memo..[c.simpleName]= c);

  factory CoffeeFlavor(name) { /* ... */ }
  // ... 
}
Getting back to Erik's suggestion, I can add a new capability to my reflectable Flavor class—the subtypeQuantifyCapability:
class Flavor extends Reflectable {
  const Flavor()
    : super(newInstanceCapability, subtypeQuantifyCapability);
}

const flavor = const Flavor();
What this means is that I can move all of the @flavor annotations from the concrete flyweight CoffeeFlavor classes and instead place one on the CoffeeFlavor class itself:
@flavor
class CoffeeFlavor {
  // ...
  static Map classMirrors = flavor.
    annotatedClasses.
    fold({}, (memo, c) => memo..[c.simpleName]= c);

  factory CoffeeFlavor(name) { /* ... */ }
  // ... 
}

class Cappuccino implements CoffeeFlavor {
  String get name => 'Cappuccino';
  double get profitPerOunce => 0.35;
}

class Espresso implements CoffeeFlavor {
  String get name => 'Espresso';
  double get profitPerOunce => 0.15;
}

// More concrete flyweight classes here...
With that, the annotatedClasses includes every class that extends or implements the annotated CoffeeFlavor class. I have the same exact code and functionality, but with a single annotation instead of one annotation per concrete class.

Furthermore, this works across libraries. If I define CoffeeFlavor and the various concrete classes in a library, but define another concrete class in the main entry point:
// The library with the factory and flyweights:
import 'package:flyweight_code/coffee_shop.dart';

// Concrete flyweight outside the library
class Mochachino implements CoffeeFlavor {
  String get name => "Mochachino";
  double get profitPerOunce => 0.3;
}

main() {
  // Go about coffee shop business here...
}
It still works. That is, the flavor constant is still aware of this Mochachino class as a "sub type".

I had thought to originally try to bend Reflectable to the point that it could mimic my original implementation. In there, I use dart:mirrors to search through all code to find classes that implement CoffeeFlavor. That seemed the most explicit implementation of what I needed—a list of available concrete classes without much overhead.

But I have to admit that Reflectable with subtypeQuantifyCapability accomplishes exactly the same thing with almost no additional overhead—just a constant or two. The resulting code is easier to read and the generated JavaScript (as I found last night) is much smaller. This is a win all around.


Day #13

Monday, November 23, 2015

Building Reflectable Dart Code with a Dependency Assist


OK, let's try that again.

Yesterday I was unable to build my Reflectable-based Dart code—either into fully assembled Dart or into JavaScript. Thanks to a hint from Sigurd Meldgaard in the comments, I am ready.

I am still exploring approaches to the Flyweight Pattern for Design Patterns in Dart. I have already more or less settled on a simple reflection approach, but am exploring code annotations for marking concrete flyweight classes, which is where Reflectable enters the story. And almost exited yesterday—until Sigurd told me that Reflectable currently requires an overridden dependency on the analyzer package.

So I add the appropriate dependency_overrides entry to my pubspec.yaml file:
name: flyweight_code
dependencies:
  reflectable: any
dependency_overrides:
  analyzer: '0.26.1+14'
transformers:
- reflectable:
    entry_points:
      - bin/coffee_orders.dart
    formatted: true
With that... everything works. My code builds without issue:
$ pub build --mode=debug bin          
Loading source assets... 
Loading reflectable transformers... 
Building flyweight_code... (3.8s) 
[Info from Dart2JS]:
Compiling flyweight_code|bin/coffee_orders.dart...
[Info from Dart2JS]:
Took 0:00:04.819196 to compile flyweight_code|bin/coffee_orders.dart.
[Info from Dart2JS]:
Compiling flyweight_code|bin/coffee_orders_reflectable_original_main.dart...
[Info from Dart2JS]:
Took 0:00:01.456035 to compile flyweight_code|bin/coffee_orders_reflectable_original_main.dart.
Built 589 files to "build".
The compiled code is compact:
$ ls -lh build/bin/coffee_orders.dart*
-rw-r--r-- 1 chris chris 5.0K Nov 24 00:17 build/bin/coffee_orders.dart
-rw-r--r-- 1 chris chris 100K Nov 24 00:17 build/bin/coffee_orders.dart.js
By way of comparison, the same code based on the built-in dart:mirrors library was nearly 300K the other night. Sure, I am still compiling 5K of Dart into 100K of JavaScript, but that's a nearly 66% improvement.

Of course, what matters most is that the code actually work, which it does. Running the compiled JavaScript in Node results in my usual coffee shop output:
$ node build/bin/coffee_orders.dart.js
Served Cappuccino to Fred.
Served Espresso to Bob.
Served Frappe to Alice.
Served Frappe to Elsa.
Served Coffee to null.
Served Coffee to Chris.
Served Mochachino to Joy.
-----
Served 7 coffee drinks.
Served 5 kinds of coffee drinks.
For a profit of: $27.2
The verdict here is that Reflectable is a huge win all around. The minor, temporary issue of a out-of-sync dependency aside, Reflectable is simply better than dart:mirrors. The resulting generated code is smaller. It is easier to build. From my perspective, the biggest win is that it makes my code much cleaner.

To find classes annotated with the custom @flavor annotation in dart:mirrors, I had to traverse libraries and declarations. It was ugly:
  static Map _allDeclarations = currentMirrorSystem().
      libraries.
      values.
      fold({}, (memo, library) => memo..addAll(library.declarations));

  static Map classMirrors = _allDeclarations.
    keys.
    where((k) => _allDeclarations[k] is ClassMirror).
    where((k) =>
      _allDeclarations[k].metadata.map((m)=> m.type.reflectedType).contains(Flavor)
    ).
    fold({}, (memo, k) => memo..[k]= _allDeclarations[k]);
The equivalent code with Reflectable is mercifully easy to read:
  static Map classMirrors = flavor.
    annotatedClasses.
    fold({}, (memo, c) => memo..[c.simpleName]= c);
The Reflectable @flavor annotation just knows the classes that it annotates. What could be easier?

That said, I am not sold on annotations as the best approach to concrete flyweight classes in Dart. I may try my original, not-annotated solution again—but with Reflectable. It could be that Reflectable is optimized for annotations, but other cases still work equally or more well in dart:mirrors. I will find out with at least one other case. Tomorrow.


Day #12

Sunday, November 22, 2015

Can't Transform My Reflectable Flyweight


Up tonight, I try compiling my Reflectable Dart code into JavaScript. Even if the compiled JavaScript is twice the size of the dart:mirrors equivalent, I would likely stick with Reflectable. The Dart code is just that pretty.

For books like Design Patterns in Dart, I tend to favor built-in libraries to external libraries—even external libraries that are maintained on the core project like Reflectable. I will make an exception for an external package that makes my job of explaining central concepts easier. Reflectable fits that criteria since it converted something like a dozen lines of library and declaration processing into flavor.annotatedClasses (flavor being a custom constant used to annotate my code).

So tonight, I try explore the other promise of Reflectable: better JavaScript compilation. Following along with the project README, I update the pubspec.yaml to include a Reflectable transformer:
name: flyweight_code
dependencies:
  reflectable: any
transformers:
- reflectable:
    entry_points:
      - bin/coffee_orders.dart
    formatted: true
Next, I run pub build to transform this code:
$ pub build --mode=debug bin                   
Loading source assets... 
Loading reflectable transformers... 
Building flyweight_code... (3.0s) 
[Info from Dart2JS]:
Compiling flyweight_code|bin/coffee_orders.dart...
[Info from Dart2JS]:
Took 0:00:01.592568 to compile flyweight_code|bin/coffee_orders.dart.
Built 600 files to "build".
Unfortunately, when I run the code from Dart, I get a bad state error:
$ dart build/bin/coffee_orders.dart                        
here!!!!!!!!!!
Cappuccino
Instance of 'Flavor'
Unhandled exception:
Bad state: Reflectable has not been initialized. Did you forget to add the main file to the reflectable transformer's entry_points in pubspec.yaml?
#0      data (package:reflectable/src/reflectable_transformer_based.dart:119:5)
#1      data (package:reflectable/src/reflectable_transformer_based.dart:118:33)
#2      ReflectableImpl.annotatedClasses (package:reflectable/src/reflectable_transformer_based.dart:1260:50)
#3      CoffeeFlavor.classMirrors (package:flyweight_code/coffee_shop.dart:61:5)
#4      CoffeeFlavor.classMirrors (package:flyweight_code/coffee_shop.dart:60:14)
#5      CoffeeFlavor.CoffeeFlavor (package:flyweight_code/coffee_shop.dart:69:11)
#6      CoffeeShop.order (package:flyweight_code/coffee_shop.dart:24:22)
#7      main (file:///home/chris/repos/design-patterns-in-dart/flyweight/build/bin/coffee_orders.dart:39:7)
#8      _startIsolate.<anonymous closure> (dart:isolate-patch/isolate_patch.dart:261)
#9      _RawReceivePortImpl._handleMessage (dart:isolate-patch/isolate_patch.dart:148)
The first few lines of output there are debug print() statements, but when I hit Reflectable code, it crashes. I am unsure that I understand the error—I clearly put the main() entry file into the pubspec.yaml. Based on the pubspec.yaml for the test_reflectable code, I think I am doing this correctly. But still, I get that error.

I try following the suggestion of the README to use build/bin/packages as the package-root, but I still get the same error:
$ dart -p ./build/bin/packages build/bin/coffee_orders.dart
here!!!!!!!!!!
Cappuccino
Instance of 'Flavor'
Unhandled exception:
Bad state: Reflectable has not been initialized. Did you forget to add the main file to the reflectable transformer's entry_points in pubspec.yaml?
#0      data (package:reflectable/src/reflectable_transformer_based.dart:119:5)
...
Not surprisingly, this also fails if I try to run the JavaScript-compiled version of the code:
$ node build/bin/coffee_orders.dart.js
here!!!!!!!!!!
Cappuccino
Instance of 'Flavor'
/home/chris/repos/design-patterns-in-dart/flyweight/build/bin/coffee_orders.dart.js:671
      throw H.wrapException(ex);
              ^
Bad state: Reflectable has not been initialized. Did you forget to add the main file to the reflectable transformer's entry_points in pubspec.yaml?
    at dart.wrapException (/home/chris/repos/design-patterns-in-dart/flyweight/build/bin/coffee_orders.dart.js:658:17)
...
And, if I compare the transformed version of the bin/coffee_orders.dart file with the original, I find no differences:
$ diff bin/coffee_orders.dart build/bin/coffee_orders.dart
$ echo $?
0
At this point, I have to admit that I am stumped. I try converting this all to a web script with identical results. No matter what I can think to try, I do not seem to get a transformed version of the Dart code that I list in my pubspec.yaml.

This is a bit of a bummer. I still might make use of Reflectable in the book. I assume that I am doing something dumb or there is a minor bug in Reflectable that will get resolved. Likely the former, but if it is the latter, it will surely be resolved long before the book is ready. I may try to identify simpler test cases or try test_reflectable myself tomorrow.

If anyone has any suggestions, my code is at: https://github.com/eee-c/design-patterns-in-dart/tree/master/flyweight.


Day #11


Saturday, November 21, 2015

Beautiful, Clean Mirrors in Dart with Reflectable


Tonight, I hope to make better Dart mirrors with the reflectable package. Better being a relative term, I hope to make my code clearer and the resulting compiled code smaller. Given my relatively small code, it may be asking too much of reflectable, but it always best to aim high.

I am still working on different approaches to the Flyweight Pattern for the forthcoming Design Patterns in Dart. The most recent tangent is exploring custom annotations that identify concrete flyweight classes in my code:
@flavor
class Cappuccino implements CoffeeFlavor {
  String get name => 'Cappuccino';
  double get profitPerOunce => 0.35;
}
The factory constructor responsible for caching flyweights uses this custom @flavor annotation to identify the Cappuccino class as a concrete flyweight that can be used in my coffee shop application.

Thanks to the built-in dart:mirrors library, I was able to get this working. Thanks to the @MirrorsUsed() annotation from dart:mirrors, I got this compiled to somewhat smallish Javascript. Let's see if reflectable can be better than "working" and "smallish."

I add reflectable to my pubspec.yaml:
name: flyweight_code
dependencies:
  reflectable: any
After a quick pub get to load the package and its dependencies, I replace the dart:mirrors import with reflectable in my coffee shop library:
library coffee_shop;

// @MirrorsUsed(metaTargets: "coffee_shop.Flavor")
// import 'dart:mirrors';

import 'package:reflectable/reflectable.dart';
// ...
With that, I get errors related to missing currentMirrorSystem method that had been defined in dart:mirrors. Let's see if I can fix that.

I start by replacing the const used for the @flavor annotation with a reflectable version:
class Flavor extends Reflectable {
  const Flavor()
    : super(newInstanceCapability);
}

const flavor = const Flavor();
I need the newInstanceCapability to replace the functionality in the factory constructor for CoffeeFlavor. With dart:mirrors that looked like:
class CoffeeFlavor {
  // ...
  factory CoffeeFlavor(name) {
    return _cache.putIfAbsent(name, () =>
        classMirrors[new Symbol(name)].
            newInstance('', []).
            reflectee
    );
  }
  // ...
}
This is the heart of the Flyweight Pattern that I am trying to replicate with reflectable. If a particular coffee flyweight is not present, this should add a single instance to the internal cache. Then, no matter how many times the same coffee flavor is ordered later, the same instance will be returned.

This code is not the most difficult aspect of using mirrors in this case. Finding the annotated classes to build that classMirrors property is a gigantic pain in dart:mirrors:
class CoffeeFlavor {
  // ...
  static Map _allDeclarations = currentMirrorSystem().
      libraries.
      values.
      fold({}, (memo, library) => memo..addAll(library.declarations));

  static Map classMirrors = _allDeclarations.
    keys.
    where((k) => _allDeclarations[k] is ClassMirror).
    where((k) =>
      _allDeclarations[k].metadata.map((m)=> m.type.reflectedType).contains(Flavor)
    ).
    fold({}, (memo, k) => memo..[k]= _allDeclarations[k]);
  // ...
}
Mercifully, the Reflectable class has just what I need: an annotatedClasses property. Since the Flavor constant used for the @flavor annotation is a subclass of Reflectable, I don't have to do any work to find the concrete, @flavor annotated, flyweight classes. I can simply use that property. All of that work then becomes just:
class CoffeeFlavor {
  // ...
  static Map classMirrors = flavor.
    annotatedClasses.
    fold({}, (memo, c) => memo..[c.simpleName]= c);
  // ...
}
Even nicer, the reflectable package makes it easier to get ahold of real objects—no need for the reflectee property. The factory constructor then becomes simply:
class CoffeeFlavor {
  // ...
  factory CoffeeFlavor(name) {
    return _cache.putIfAbsent(name, () =>
        classMirrors[name].
            newInstance('', [])
    );
  }
  // ...
}
That is a big win for overall readability of my mirror-based Dart code. Content, I stop here for today. I will pick back up with transforming this code into JavaScript tomorrow. And unless it generates gigabyte-sized code, I have the feeling that the reflectable package will become my go-to solution for mirrors in Dart. That is some pretty mirror code!


Day #10

Friday, November 20, 2015

Impact of Reflection on Annotations in Dart


I had a good time messing about with code annotations last night. Ostensibly I am still working on the Flyweight Pattern in Dart for the forthcoming Design Patterns in Dart. Tonight, however, I am really just exploring annotations a little further.

I am somewhat surprised that the DartPad for last night's code (https://dartpad.dartlang.org/c7dabc0c57a93e8d88d7) compiled. I am a little fuzzy on the details of DartPad, but there has to be some JavaScript compilation taking place to make it work. The thing is, when I compile last night's code into JavaScript, it is huge.

The code itself is a little over 4k of Dart:
$ ls -lh bin/coffee_orders.dart lib/coffee_shop.dart 
-rwxr-xr-x 1 chris chris 1.6K Nov 21 00:12 bin/coffee_orders.dart
-rw-r--r-- 1 chris chris 2.8K Nov 21 00:18 lib/coffee_shop.dart
But when I compile it:
$ dart2js bin/coffee_orders.dart -o bin/tmp.js                                                                 
bin/coffee_orders.dart:
Warning: 
****************************************************************
* WARNING: dart:mirrors support in dart2js is experimental,
*          and not recommended.
*          This implementation of mirrors is incomplete,
*          and often greatly increases the size of the generated
*          JavaScript code.
*
* Your app imports dart:mirrors via:
*   coffee_orders.dart => package:flyweight_code => dart:mirrors
*
* You can disable this message by using the --enable-experimental-mirrors
* command-line flag.
*
* To learn what to do next, please visit:
*    http://dartlang.org/dart2js-reflection
****************************************************************


Hint: 2 hint(s) suppressed in package:flyweight_code.
Hint: When run on the command-line, the compiled output might require a preamble file located in:
  /lib/_internal/js_runtime/lib/preambles.
bin/coffee_orders.dart:
Hint: 2367 methods retained for use by dart:mirrors out of 3519 total methods (67%).

bin/packages/flyweight_code/coffee_shop.dart:4:1:
Info: This import is not annotated with @MirrorsUsed, which may lead to unnecessarily large generated code.
Try adding '@MirrorsUsed(...)' as described at https://goo.gl/Akrrog.
import 'dart:mirrors';
^^^^^^^^^^^^^^^^^^^^^^
I get nearly 4k of console warnings.

I kid, I kid. What is not funny however, is that, as the warning suggests, I get very large JavaScript output:
ls -lh bin/tmp.js
-rw-r--r-- 1 chris chris 1.7M Nov 21 00:25 bin/tmp.js
1.7Mb is insane.

The code works (if I follow the warning about preambles):
$ cat ~/local/dart/dart-sdk/lib/_internal/js_runtime/lib/preambles/d8.js bin/tmp.js > bin/coffee_orders.dart.js
$ node bin/coffee_orders.dart.js
Served Cappuccino to Fred.
Served Espresso to Bob.
Served Frappe to Alice.
Served Frappe to Elsa.
Served Coffee to null.
Served Coffee to Chris.
Served Mochachino to Joy.
-----
Served 7 coffee drinks.
Served 5 kinds of coffee drinks.
For a profit of: $27.2
But 1.7Mb is not going to fly.

I annotated my concrete flyweight classes with the Flavor constant:
// Annotation Class
class Flavor { const Flavor(); }
// Annotation instance
const flavor = const Flavor();

@flavor
class Cappuccino implements CoffeeFlavor {
  String get name => 'Cappuccino';
  double get profitPerOunce => 0.35;
}
// Other concrete instances...
So, I ought to be able to slim the resultant JavaScript down simply by telling dart2js that it only has to worry about mirrors for Flavor. This is what the @MirrorsUsed annotation does. In my case, I am using mirrors as "meta targets" -- reading annotation / metadata from the code itself. I add the corresponding @MirrorsUsed() annotation before the import of dart:mirrors:
library coffee_shop;

@MirrorsUsed(metaTargets: "coffee_shop.Flavor")
import 'dart:mirrors';
// ...
Now, when I compile my code, dart2js only retain 38 methods for use with mirrors instead of 2367:
$ dart2js bin/coffee_orders.dart -o bin/tmp.js --enable-experimental-mirrors
bin/coffee_orders.dart:
Hint: 38 methods retained for use by dart:mirrors out of 629 total methods (6%).

bin/packages/flyweight_code/coffee_shop.dart:4:1:
Info: Import of 'dart:mirrors'.
import 'dart:mirrors';
^^^^^^^^^^^^^^^^^^^^^^
That is bound to lead to some smaller compiled code. And indeed, it comes in nearly 90% smaller than before:
$ cat ~/local/dart/dart-sdk/lib/_internal/js_runtime/lib/preambles/d8.js bin/tmp.js > bin/coffee_orders.dart.js
$ ls -lh bin/tmp.js bin/coffee_orders.dart.js                                                                  
-rw-r--r-- 1 chris chris 294K Nov 21 00:36 bin/coffee_orders.dart.js
-rw-r--r-- 1 chris chris 284K Nov 21 00:35 bin/tmp.js
That seems a fine stopping point for tonight. I will continue this exploration tomorrow with reflectable, a potential replacement for dart:mirrors.


Day #9

Thursday, November 19, 2015

Creating and Reading Dart Annotations in Flyweights


I am settling comfortably into Dart mirrors as a solution for obtaining concrete instances in the Flyweight pattern. They are not a one-size-fits-all solution, but they strike a nice balance between usability in the client context (especially when paired with Dart's factory constructors) and maintainability of the flyweight code. That said, I do not want to leave reasonable options unexplored.

While reasonable people can disagree on what reasonable options are, I felt the siren's song of code annotation more than once while working with this pattern. So today, I give into that temptation. Hopefully I won't be dashed on rocks for my trouble.

While working other angles on the problem of concrete classes, annotations were appealing mostly because of their constant nature. My current CoffeeFlavor interface is a regular (non-constant) class:
class CoffeeFlavor {
  // Lots of static, mirror code from last night here...
  // Factory constructor:
  factory CoffeeFlavor(name) {
    return _cache.putIfAbsent(name, () =>
        classMirrors[new Symbol(name)].
            newInstance(new Symbol(''), []).
            reflectee
    );
  }
  // Normal class stuff:
  String get name => "Fake Coffee";
  double get profitPerOunce => 0.0;
}
Concrete implementations that get used as flyweights are similarly non-constant:
class Cappuccino implements CoffeeFlavor {
  String get name => 'Cappuccino';
  double get profitPerOunce => 0.35;
}
Due to the factory constructor, various solutions to the flyweight caching felt like a constant was the only solution. In the end, I could not make them work — hence last night's mirror solution.

Somewhere in my brain I thought that, since annotations are constants, maybe they can help here. But now that I am faced with the blank page, all I can think to do is mark a concrete class with an annotation to help finding and caching it:
@flavor
class Cappuccino implements CoffeeFlavor {
  String get name => 'Cappuccino';
  double get profitPerOunce => 0.35;
}
That seems to offer nothing new over yesterday's solution which made use of the implemented interface to find concrete classes. If anything, the annotation is one extra line.

Still, while I am here, it might be fun to write some Dart code that can read and apply annotations. I start by defining the class and annotation const:
// Annotation Class
class Flavor { const Flavor(); }
// Annotation instance
const flavor = const Flavor();
Yesterday's code found concrete classMirrors by filtering for “super interfaces” that contained CoffeeFlavor:
  static Map classMirrors = _allDeclarations.
    keys.
    where((k) => _allDeclarations[k] is ClassMirror).
    where((k) =>
      _allDeclarations[k].superinterfaces.contains(reflectClass(CoffeeFlavor))
    ).
    fold({}, (memo, k) => memo..[k]= _allDeclarations[k]);
Tonight, I need to similarly work though all class declarations, but filter on metadata (annotations):
  static Map classMirrors = _allDeclarations.
    keys.
    where((k) => _allDeclarations[k] is ClassMirror).
    where((k) =>
      _allDeclarations[k].metadata.map((m)=> m.type.reflectedType).contains(Flavor)
    ).
    fold({}, (memo, k) => memo..[k]= _allDeclarations[k]);
The _allDeclarations.keys is a map of symbols (e.g. #Cappuccino) pointing to declaration mirrors. So iterating over all the keys, then filtering on _allDeclarations[k] gives me individual declarations like the concrete class definition. From there, I map the annotations/metadata to the corresponding annotation type. In this case I want the Flavor annotation so that any classes with the Flavor annotation are returned.

If I had declared Flavor with properties and set them in the const declaration, then I could get those properties with the getField() method. Here, however, I just need to know if the @flavor annotation is being used. So I am already done!

My code continues to pass dartanalyzer and the coffee shop code that relies on this flyweight code similarly continues to work. Annotations do not buy me anything substantive in this case (at least that I can see). Still it is good to know how to extract and apply them.

(Play with this code on DartPad: https://dartpad.dartlang.org/c7dabc0c57a93e8d88d7)


Day #8

Wednesday, November 18, 2015

Locking Down Flyweights Mirrors in Dart


At the risk of over-examining a topic beyond all reason, I continue tonight to explore Dart mirrors as a means of obtaining concrete Flyweight objects. Hey, if you can't over-examine a topic when blogging every day, when can you?

I very much like yesterday's mirror approach. In my coffee shop example, the CoffeeFlavor reference class is responsible for identifying concrete flyweights. The calling code behaves just like it would if it were getting a generic CoffeeFlavor instance:
  void order(name, sizeName, {who, fooFoo}) {
    var flavor = new CoffeeFlavor(name);
    int size = sizes[sizeName];
    _orders.add(new Order(flavor, size, who, fooFoo));
  }
But the factory constructor in CoffeeFlavor is looking up concrete classes (e.g. Cappuccino, Latte, etc). in its internal cache:
class CoffeeFlavor {
  // ...
  factory CoffeeFlavor(name) =>
    _cache.putIfAbsent(name, () =>
        classMirrors[new Symbol(name)].
           newInstance(new Symbol(''), []).
           reflectee
    );
  // ...
}
If present, the previously created concrete instance — the flyweight — is returned. If it is not already present, then the concrete class is looked up in the current library and used to create the flyweight. This approach has the dual benefit of keeping the client code clean (it thinks it is creating an instance of CoffeeFlavor) and keeping the concrete classes simple.

The concrete classes need only define intrinsic properties of particular coffee flavors:
class Cappuccino implements CoffeeFlavor {
  String get name => 'Cappuccino';
  double get profitPerOunce => 0.35;
}
No metadata required (I may explore that tomorrow, though). No tomfoolery needed just to support the factory. It's all clean.

I think I can make this even better by restricting the map of classMirrors to just classes that implement CoffeeFlavor. Just because I am using mirrors doesn't give me license to be obscene. This is statically typed Dart, not some loosey-goosey dynamically typed language.

That turns out to be a little harder than expected. First off, I need to grab the list of all declarations from the local mirror:
class CoffeeFlavor {
  // ...
  static Map _allDeclarations = currentMirrorSystem().
      findLibrary(#coffee_shop).
      declarations;
  // ...
}
There is no pairs accessor for Dart maps, so I have to iterate over all of the keys in the _allDeclarations map. From there, I filter only class mirror declarations, and only classes that implement the CoffeeFlavor interface. Lastly, I reassemble the map via a fold():
class CoffeeFlavor {
  // ...
  static Map _allDeclarations = currentMirrorSystem().
      findLibrary(#coffee_shop).
      declarations;

  static Map classMirrors = _allDeclarations.
    keys.
    where((k) => _allDeclarations[k] is ClassMirror).
    where((k) =>
      _allDeclarations[k].superinterfaces.contains(reflectClass(CoffeeFlavor))
    ).
    fold({}, (memo, k) => memo..[k]= _allDeclarations[k]);
  // ...
}
That's a little verbose. It does the trick, but I am unsure if it is worth all of the noise.

Now that I think about it, it would be nice if this could work across libraries. My coffee_shop library can define a bunch of coffee flavor classes, but it would be helpful to support coffee flavor classes in the main code file as well:
class Mochachino implements CoffeeFlavor {
  String get name => "Mochachino";
  double get profitPerOunce => 0.3;
}

main() {
  var shop = new CoffeeShop()
    ..order('Cappuccino', 'large', who: 'Fred', fooFoo: 'Extra Shot')
    ..order('Espresso',   'small', who: 'Bob')
    ..order('Frappe',     'large', who: 'Alice')
    ..order('Frappe',     'large', who: 'Elsa', fooFoo: '2 Percent Foam')
    ..order('Coffee',     'small')
    ..order('Coffee',     'medium', who: 'Chris')
    ..order('Mochachino', 'large', who: 'Joy');
  // ...
}
To make that work, I need to rework the _allDeclarations assignment. Instead of looking in the current, coffee_shop library, I have to look across all libraries:
class CoffeeFlavor {
  // ...
  static Map _allDeclarations = currentMirrorSystem().
      libraries.
      values.
      fold({}, (memo, library) => memo..addAll(library.declarations));
  // ...
}
Again, I have to work around the lack of a pairs iterable on Map. That aside, this works nicely. My customers can order plenty of Mochachinos at the local coffee shop even if corporate does not support them yet.

There is definitely some power in all these Dart mirrors. That power may not always be necessary, but it is nice to know that it is there if I need it.

(Play with this code on DartPad: https://dartpad.dartlang.org/d103fcc8e1cbf371fa04)


Day #7

Tuesday, November 17, 2015

Concrete Flyweight Objects with Dart Mirrors


I worried that last night's post on concrete Flyweight objects in Dart would be too easy to warrant a post. Then I actually tried to write the code.

So it turns out that we are not allowed to create compile-time static variables in Dart—and haven't been allowed for quite some time. Well, we are allowed, but they will not be evaluated until explicitly invoked. This thwarted my plan to use these static variable declarations to register themselves as flyweight implementations.

But the challenge remains. I would very much like to create concrete instances of flyweight objects without resorting to ickery like case statements. Tonight, I explore the dreaded mirrors to accomplish this.

Sidenote: I understand that there is a StackOverflow topic on this very question. I am purposefully not reading that discussion so that I can explore the topic fresh here. The answer on StackOverflow is likely far superior to mine. So let's get to mine!

In my current coffee shop example, I would like to register orders along the lines of:
var shop = new CoffeeShop()
    ..order('Cappuccino', 'large', who: 'Fred', fooFoo: 'Extra Shot')
    ..order('Espresso',   'small', who: 'Bob')
    ..order('Frappe',     'large', who: 'Alice')
    ..order('Frappe',     'large', who: 'Elsa', fooFoo: '2 Percent Foam')
    ..order('Coffee',     'small')
    ..order('Coffee',     'medium', who: 'Chris');
Over the course of the day, I expect there to be a large number of orders so I want to minimize the number of objects retained in memory. Enter the flyweight.

Specifically, the intrinsic properties of a coffee flavor like “Cappuccino” do not change. The size, the orderer, and silly additional instructions change with each order, but a Cappuccino stays a Cappuccino all day long. So I make this a flyweight object.

Thanks to Dart's factory constructors, I do not even require a factory class to accomplish this. From the outside, creating new CoffeeFlavor instances looks just like creating any other object:
class CoffeeShop {
  void order(name, sizeName, {who, fooFoo}) {
    var flavor = new CoffeeFlavor(name); // Looks like a regular constructor!!!
    int size = sizes[sizeName];
    _orders.add(new Order(flavor, size, who, fooFoo));
  }
  // ...
}
Before introducing concrete classes for the various coffee flavors, this factory constructor simply looked up a previously used flyweight in a cache:
class CoffeeFlavor {
  // ... 
  factory CoffeeFlavor(name) =>
      _cache.putIfAbsent(name, () => new CoffeeFlavor._(name));
  // ...
}
Instead of a vanilla CoffeeFlavor object, I want an actual instance of Cappuccino:
class FakeCoffee implements CoffeeFlavor {
  String get name => "Fake Coffee";
  double get profitPerOunce => 0.0;
}
For that, I think I will need mirrors. I start by importing dart:mirrors:
library coffee_shop;

import 'dart:mirrors';
Next, I need to find a mirror for the current library (coffee_shop):
      var m = currentMirrorSystem().findLibrary(#coffee_shop);
In the list of declarations of my library mirrors, I can get a class mirror for a given name (e.g. "Cappuccino"):
      var c = m.declarations[new Symbol(name)];
Finally, I can get a new instance of that class:
      return c.newInstance(new Symbol(''), []).reflectee;
Putting this altogether, my factory constructor becomes:
class CoffeeFlavor {
  // ...
  factory CoffeeFlavor(name) =>
    _cache.putIfAbsent(name, (){
      var m = currentMirrorSystem().findLibrary(#coffee_shop);

      var c = m.declarations[new Symbol(name)];
      return c.newInstance(new Symbol(''), []).reflectee;
    });
  // ...
}
I still use a putIfAbsent() to build up the cache—only now it creates concrete instances from mirrors.

There are several things to like about this approach. The client context is still blissfully unaware that the Flyweight pattern is in play—it still creates new CoffeeFlavor objects only to receive a flyweight subclass instead. I also like that this approach returns concrete instances of flyweight objects. I may not always need to do so, but it is good to know that this is possible. Lastly, I appreciate that I can accomplish this without a case statement.

There are drawbacks, however, to this approach. The Flyweight is intended to save memory, ideally to speed the code up. This approach relies entirely on mirrors which are not exactly high-performance beasties. That said, once the cache is populated, reflection is no longer used so the initial performance hit of mirrors could easily be overcome by later optimizations. It all depends on the context in which the code is being used.

(Play with this code on DartPad: https://dartpad.dartlang.org/c731673e2055fc97db79)


Day #6

Monday, November 16, 2015

Lazy Initialization Wins Out


Design patterns trend mundane once you figure them out. "Oh, that's all the Flyweight is?" Given that they were originally inspired by something as fanciful as The Timeless Way of Building, I still half expect the sublime from every design pattern that I explore. The sublime may not always be there. Then again, maybe I just need to explore a little more.

I enjoy finding examples that are concise yet still show some of the power of design patterns. Certainly such examples are important for Design Patterns in Dart. But once I have them, I fear tweaking them and exploring further will yield diminishing returns—perhaps the sublime just isn't in this design pattern. On the other hand, how can I ever find the sublime if I don't explore. And so tonight I risk wasting my time in search of the sublime.

The esteemed James Hurford supplied some pointers and suggestions to my recent flyweight coffee shop. The code was excellent, as to be expected. Well, except for this bit in the flyweight:
abstract class Coffee {
  factory Coffee.create(name) => _cache.putIfAbsent(name, () => _create(name));    
  static Coffee _create(name) {
    switch(name) {
      case 'Flat White':
        return new FlatWhite();
      case 'Mockachino':
        return new Mockachino();
      case 'Cappuccino':
        return new Cappuccino();
      case 'Espresso':
        return new Espresso();
      case 'Frappe':
        return new Frappe();
      case 'Long Black':
        return new LongBlack();
      case 'Americano':
        return new Americano();
    }
    
    return new FakeCoffee();
  }
}
I'm not giving James too hard a time here. The code has two things that I appreciate: it works and it produces concrete flyweight instances of different varieties. I always like working code and I appreciate concrete instances because Dart's static typing is one of the things I very much want to explore in the book.

But that case statement: ick. Not only is it long and unsightly, but it also necessitates two changes every time a new coffee drink is added to the menu. Maybe the load-time fun from last night can help. Or not...

Following along with the DWT approach, I ought to be able to define a concrete flyweight along the lines of:
class Mochachino implements Coffee {
  static var type = Coffee.register(new Mochachino());
  String get name => "Mochachino";
  double get profitPerOunce => 0.3;
}
Registering the Mochachino will cache a reference to the flyweight instance such that all future instances will be the original. Except this does not work.

I did not give this enough thought last night, but the DWT must be so old that some of the code, the flyweight implementation included, no longer works because of lazy initialization. Lazy initialization is great until you expect code like the type assignment to be evaluated at compile time.

For type to be registered at compile-time, I need to use the const keyword instead of new. Unfortunately, adding objects to a Map at compile-time does not lend itself to compile-time constants.

In other words, I think I'm out of luck. If I want concrete flyweight objects, I either need to stick with James' long case statement approach or move away from factory constructor back to factory classes. Neither is particular appealing, but I might opt for the latter as that was how the original pattern was envisioned. That is something to explore tomorrow.



Day #5

Sunday, November 15, 2015

Searching for Flyweight


As part of Design Patterns in Dart, I would very much like to include examples of the various patterns in the wild. I have not quite figured out how to go about doing that, so if anyone knows where to find examples of the Flyweight pattern in the wild, I would appreciate it.

I know from the very excellent Game Programming Patterns (seriously, it's great, I just bought another copy so I could read it in epub) that graphics programming tries to make extensive use of the Flyweight pattern. I dug around a bit today, but it does not seem that WebGL supports it yet. Even if did, the Flyweight would be in the WebGL API, not in Dart, so that seems unlikely

Instead of playing around with forced examples in Three.dart, I change tact. I clone a bunch of Dart repositories that are trending on GitHub, then grep through them in the hope of finding a mention of the word "flyweight":
➜  trending-dart-repos  ack -i flyweight
➜  trending-dart-repos  echo $?
1
No luck there. Still, not a complete waste of time, as I expect to find other patterns in the top results:I will add to that list over time, but that seems a good start. I have looked through code in several of those already and know that there are plenty of pattern examples.

That does not help with my goal tonight. What does help, is the search interface on GitHub, which allows me to search all Dart projects by keyword:



Most of those results look to be from goofballs compiling examples of design patterns. One in the list, however, does include an actual Flyweight pattern. The Dart Web Toolkit, which is based on the same idea as GWT. The projects looks un/lightly maintained, so it's not a strong example, but the Flyweight pattern is definite present.

The idea is to cache event mappings between native and DWT events. The DomEvent class caches these in the private _registered map:
abstract class DomEvent extends DwtEvent implements HasNativeEvent {
  // ...
  static Map<String, DomEventType> _registered;
  // ...
}
Whenever a new type is created by the factory class, it registers the DWT / native event pair under the string description of the event:
class DomEventType<H> extends EventType<H> {
  String eventName;
  DomEvent flyweight;

  DomEventType(this.eventName, this.flyweight) {
    DomEvent.getRegistered()[eventName] = this;
  }
}
Every single event in the library then registers itself at runtime when the class is evaluated:
class TouchMoveEvent extends TouchEvent {
  /**
   * The event type.
   */
  static DomEventType<TouchMoveHandler> TYPE = new DomEventType<TouchMoveHandler>(BrowserEvents.TOUCHMOVE, new TouchMoveEvent());
  // ...
}
This way, whenever the framework needs a touch-move event, it can use the flyweight registered when the class assigns the TYPE variable. Nice!

As I said, I am unsure if the qualifies as a strong example. I suppose if I can find that folks are still using the library, then it qualifies. Regardless, I am happy to have rediscovered the GitHub language search. I have the feeling this will come in quite handy.


Day #4

Saturday, November 14, 2015

Flyweight Coffee Shop in Dart


The current Flyweight pattern example with which I have been playing is vaguely unsatisfying to me. I co-opted a tree decoration example from the Wikipedia article and it seemed a nice start. I know it is just an example, but it does not feel like something from the real-world. Plus it really seemed like it had two flyweights in there, confusing things.

Eventually, I'd like to pull find some real-world examples (anyone know where flyweight was used in live Dart code?), but for now, I am going to play with the Scala example from the same Wikipedia article. It is a coffee-ordering example so that ought to feel more real.

Borrowing from the Scala coffee shop example, I would to be able to deliver a bunch of orders to different people. At the end of the day, I would like to be able to tally up some totals. The main thread of the application should look something like:

main() {
  var shop = new CoffeeShop()
    ..order('Cappuccino', 'large',  who: 'Fred', fooFoo: 'Extra Shot')
    ..order('Espresso',   'small',  who: 'Bob')
    ..order('Frappe',     'large',  who: 'Alice')
    ..order('Frappe',     'large',  who: 'Elsa', fooFoo: '2 Percent Foam')
    ..order('Coffee',     'small')
    ..order('Coffee',     'medium', who: 'Chris');

  shop.serve();
  print('-----');
  print(shop.report);
}
The flyweight in this example will be the coffee "flavor" (Cappuccino, Espresso, Coffee, etc.). Intrinsic to the coffee flavor is the name and maybe some nutritional information or cost data. The rest of the information is specific to the order: who placed it, the size, and any silly instructions.

The Order class would be something simple along the lines of:
class Order {
  CoffeeFlavor flavor;
  int size;
  String instructions;
  String who;

  Order(this.flavor, this.size, this.who, this.instructions);

  String get service => "${flavor.name} to ${who}";
}
I am going to stick with last night's factory constructor (instead of the previous night's factory class). So the flyweight + factory is:
class CoffeeFlavor {
  static Map _cache = {};
  static int get totalCount => _cache.length;

  factory CoffeeFlavor(name) =>
      _cache.putIfAbsent(name, () => new CoffeeFlavor._(name));

  String name;
  CoffeeFlavor._(this.name);
}
What's left is the CoffeeShop class which is responsible for keeping a list of orders for serving and for end-of-day reporting. To handle orders as above, the order() method should look something like:
  void order(name, sizeName, {who, fooFoo}) {
    var flavor = new CoffeeFlavor(name);
    int size = sizes[sizeName];
    _orders.add(new Order(flavor, size, who, fooFoo));
  }
The rest of the class declares the private list of _orders and a mapping of size names to fluid ounces:
class CoffeeShop {
  static Map sizes = {
    'small': 8,
    'medium': 12,
    'large': 20
  };

  List _orders = [];

  void order(name, sizeName, {who, fooFoo}) {
    var flavor = new CoffeeFlavor(name);
    int size = sizes[sizeName];
    _orders.add(new Order(flavor, size, who, fooFoo));
  }
}
Next, I need a method to serve drinks:
  void serve() {
    _orders.forEach((o) { print("Served ${o.service}.");});
  }
Finally, I can define a simple report getter to produce some daily stats:
  String get report => "Served ${_orders.length} coffee drinks.\n"
      "Served ${CoffeeFlavor.totalCount} kinds of coffee drinks.\n";
With that, I can run a coffee shop:
Served Cappuccino to Fred.
Served Espresso to Bob.
Served Frappe to Alice.
Served Frappe to Elsa.
Served Coffee to null.
Served Coffee to Chris.
-----
Served 6 coffee drinks.
Served 4 kinds of coffee drinks.
That is very similar to what I had the previous night with the tree example, but it does have a more real world feel to it. At least to this coffee drinker.

What I am keen to explore next is building with additional properties that are intrinsic to the CoffeeFlavor flyweight object. For instance, what if each flavor had a profit of $USD0.10 per fluid ounce except for "Frappe" drinks, which are $USD0.50? That could be represented in the flyweight as a profitPerFluidOunce getter method:
class CoffeeFlavor {
  //...
  float get profitPerOunce => name == 'Frappe' ? .5 : 0.1;
}
The Order class can then determine profit for each order instance:
class Order {
  //...
  float get profit => size * flavor.profitPerOunce;
}
Now the coffee shop report can quickly include the day's take:
class CoffeeShop {
  // ...
  String get report => "Served ${_orders.length} coffee drinks.\n"
      "Served ${CoffeeFlavor.totalCount} kinds of coffee drinks.\n"
      "For a profit of: \$${profit}";

  float get profit {
    var sum = 0;
    _orders.forEach((o){ sum += o.profit; });
    return sum;
  }
}
Which results in a profit of a little over $USD24 for a handful of drinks:
Served 6 coffee drinks.
Served 4 kinds of coffee drinks.
For a profit of: $24.8
Nice!

I appreciate this example's "real world" feel. What I most appreciate about it is the obvious ability to add intrinsic properties to the flyweight—and a quick way to use them.

(Try it on DartPad: https://dartpad.dartlang.org/c5d130cf24ddbbab6a11)

Day #3


Friday, November 13, 2015

Factory Class vs. Factory Constructor in Flyweight


Unneeded patterns excite me at least as much as the tried-and-true ones. As I mentioned in the kickoff post for this latest chain, I am eager to explore a modern take on Design Patterns through the lovely lens of Dart.

I was reasonably happy with last night's implementation of the Flyweight pattern. As pointed out to me by the esteemed Matthew Butler, I might be missing some Dart goodness that could clean up my code. Don Olmstead also reported “quite a few style nits looking through your code,” but I'm pretty sure that guy's just crazy (I kid! I'm using dartfmt from now on).

At any rate, Matthew's most interesting suggestion was to convert last night's LampFactory class into a factory constructor. I think he has a valid point. The factory class was responsible for caching the flyweight:
// dartfmt'd -- happy Don? :P
class LampFactory {
  var cache = {};
  Lamp findLamp(color) {
    return cache.putIfAbsent(color, () => new Lamp(color));
  }

  int get totalCount => cache.length;
}
The flyweight class in this simple example described a lamp of varying color:
class Lamp {
  String color;
  Lamp(this.color);
}
Per Matthew's suggestion, I can eliminate the factory class in favor of the Dart factory constructor:
class Lamp {
  String color;
  static Map _cache = {};

  factory Lamp(color) =>
    _cache.putIfAbsent(color, () => new Lamp._(color));

  Lamp._(this.color);

  static int get totalCount => _cache.length;
}
That saves a few lines of code (mostly the class declaration for the factory), but I dunno. The Lamp class seems muddled now that it does two, distinct things. Maybe it is better with the caching code and the “intrinsic lampness” of the flyweight separated:
class Lamp {
  static Map _cache = {};
  static int get totalCount => _cache.length;

  factory Lamp(color) =>
    _cache.putIfAbsent(color, () => new Lamp._(color));

  String color;
  Lamp._(this.color);
}
Were I writing this in real life, I would likely leave it as is. And it does retain the spirit of the flyweight pattern—reducing the number of objects with the same intrinsic properties.. In the spirit of "patterns" however, I remain unsure.

What I do know is that this approach significantly improves the Tree context class. Instead of a bunch of references to factory-this, factory-that:
class Tree {
  int count = 0;
  var _lampFactory;

  Tree() {
    _lampFactory = new LampFactory();
  }

  void hangLamp(color, branchNumber) {
    new TreeBranch(branchNumber)
      ..hang(_lampFactory.findLamp(color));

    count++;
  }

  String get report => "Added ${count} lamps.\n"
      "Used ${_lampFactory.totalCount} kinds of lamps.";
}
The Tree now looks exactly like it would if the flyweight pattern were not in play:
class Tree {
  int count = 0;

  void hangLamp(color, branchNumber) {
    new TreeBranch(branchNumber)
      ..hang(new Lamp(color));

    count++;
  }

  String get report => "Added ${count} lamps.\n"
      "Used ${Lamp.totalCount} kinds of lamps.";
}
That cleanliness seems very much worth a little muddiness in the flyweight class.

In fact, I can use the same approach to convert the TreeBranch class into a flyweight as well—without making a change to the Tree context class:
class TreeBranch {
  static Map _cache = {};
  static int get totalCount => _cache.length;

  factory TreeBranch(number) =>
    _cache.putIfAbsent(number, () => new TreeBranch._(number));

  int number;
  TreeBranch._(this.number);
  // ...
}
Were I to stick with the factory class approach, I would have to introduce more factory objects into the calling context that already seemed lousy with them.

So my preliminary conclusion is that yes, factory constructors do seem of value with the Flyweight pattern in Dart. The ability to implement in-place without changing the context is nice, but I most appreciate the cleanliness of the resulting context code. I have the benefits of the flyweight pattern without the ugliness of factory instance variables polluting things.


Day #2