What to Build?

In ActionScript 3.0 Builder Design Pattern Part I, we set up a vacation-building site using trace statements to display different characteristics. To make these characteristics come alive and work in some practical matter, the goal is to create a builder that does the following:

• Load an external graphic
• Play a video that can be displayed in any format used by Flash Media Server or Progressive Download
• Display a different background for each vacation destination. The background is made of an external .swf file
• Present text write-up using external text source

In looking at those four actions, you might be thinking, that’s not exactly rocket science. You’d be right. However, when you start adding more and more vacation destinations, keeping track of everything can dampen one’s resolution. With the Builder, though, I found it very easy to add, change, and delete. In fact, I encourage you to add your own favorite vacation place and add it using the builder described in this post.

The Design

In Part I, I talked about different variations in the Builder’s design. The one we’re using closely follows the first as far as the Product class is concerned. All of the concrete builder classes use the same Product class. The Product class assembles the different parts under construction. However, in order to keep the Product class manageable, I added several Helper classes to take care of the details for the different parts that need to be built for the final product. Figure 1 shows the file pattern for the design:

Figure 1: File Class Diagram of Builder Design Pattern

As you can see, several classes use the Product class, and it uses all of the helper classes. Even the Client holds a reference to the Product class. As far as design is concerned, though, this one is identical to the one we used in Part I with the added helper classes.

The Client Class

One of the interesting features of the Client class in this design is that it initiates the request through the Director and then holds a reference to the Product whose creation it initiated. (It’s sort of like throwing a ball and then running to catch it.) To see the path initiated by the Client’s request consider the following sequence:

1. private var director:Director=new Director();
   Client instantiates instance of the Director class. The Director has a single method, construct, and instantiating an instance of Director makes the construct method available.
2. private var trip1:IBuilder=new ConcreteBuilder1();
   A variable specifies which concrete product it wants constructed.
3. private var srilanka:Product;
   A reference is established in a variable to the Product.
4. director.construct(trip1);
   The Director instance constructs the specified concrete builder
5. srilanka=trip1.getResult();
   The Builder instance passes the constructed elements to the Product reference
6. srilanka.disclose();
   The Product variable creates the details of the concrete builder using the helper classes to handle the details of each element. It takes care of housekeeping chores by removing the previous build from the display list.

The following listing shows the entire Client class. The constructor function brings up a background and places the buttons on the display list. I suppose there’s some irony in throwing together a “home page” with no information other than three buttons and the background pattern. I could have added all of the elements that the individual vacation destinations include, but instead I kept it open for anyone who wants to add a more substantial home page.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

 package
{
	import flash.display.Sprite;
	import fl.controls.Button;
	import flash.events.MouseEvent;
 
	public class Client extends Sprite
	{
		private var magicCarpet:Sprite=new Sprite();
		private var navContainer:Sprite=new Sprite();
		private var il:ImageLoader;
 
		private var director:Director=new Director();
 
		//Concrete builders
		private var trip1:IBuilder=new ConcreteBuilder1();
		private var trip2:IBuilder=new ConcreteBuilder2();
		private var trip3:IBuilder=new ConcreteBuilder3();
		//Products
		private var srilanka:Product;
		private var sanfrancisco:Product;
		private var prague:Product;
		//Buttons
		private var btn1:Button=new Button();
		private var btn2:Button=new Button();
		private var btn3:Button=new Button();
 
		public function Client()
		{
			il=new ImageLoader("vacationBG.swf");
			addChild(magicCarpet);
			magicCarpet.addChild(il);
			addChild(navContainer);
			setButtons();
		}
 
		private function setButtons():void
		{
			btn1.x=16;
			btn1.y=64;
			btn1.label="Sri Lanka";
			btn1.addEventListener(MouseEvent.CLICK,goSriLanka);
			navContainer.addChild(btn1);
 
			btn2.x=16;
			btn2.y=96;
			btn2.label="San Francisco";
			btn2.addEventListener(MouseEvent.CLICK,goSanFrancisco);
			addChild(btn2);
 
			btn3.x=16;
			btn3.y=128;
			btn3.label="Prague";
			btn3.addEventListener(MouseEvent.CLICK,goPrague);
			navContainer.addChild(btn3);
		}
 
		private function goSriLanka(e:MouseEvent):void
		{
			carpetCleaner();
			director.construct(trip1);
			srilanka=trip1.getResult();
			srilanka.disclose();
			magicCarpet.addChild(srilanka);
		}
 
		private function goSanFrancisco(e:MouseEvent):void
		{
			carpetCleaner();
			director.construct(trip2);
			sanfrancisco=trip2.getResult();
			sanfrancisco.disclose();
			magicCarpet.addChild(sanfrancisco);
		}
 
		private function goPrague(e:MouseEvent):void
		{
			carpetCleaner();
			director.construct(trip3);
			prague=trip3.getResult();
			prague.disclose();
			magicCarpet.addChild(prague);
		}
 
		private function carpetCleaner():void
		{
			while(magicCarpet.numChildren > 0)
			{
				magicCarpet.removeChildAt(0);
			}
		}
	}
}

As you can see, the Client is pretty busy, and as the number of vacation destinations grows the Client will need the assistance of helper classes to generate the necessary UIs to handle a wider variety of requests.

The Director Class and IBuilder Interface

In some respects the Director is like a template method. It lines up the operations required to build a product. However, the operations all use the builder interface (IBuilder) to set up the steps to put everything together. What’s more, both the Director and IBuilder are identical to the same class and interface used in the abstract Builder used in Part I. The following listing shows the two unchanged design participants:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

//Director
package
{
	public class Director
	{
		public function construct(builder:IBuilder):void
		{
			builder.buildHotel();
			builder.buildSight();
			builder.buildEvent();
			builder.buildWriteUp();
		}
	}
}
 
//Builder interface
package
{
	interface IBuilder
	{
		function buildHotel():void;
		function buildSight():void;
		function buildEvent():void;
		function buildWriteUp():void;
		function getResult():Product;
	}
}

The IBuilder interface holds a reference to the Product in the getResult() method. In this particular design, I added it because all of the concrete builder classes use the method. By doing so, I was able to type the individual concrete builders to the interface (keeping things loose) and then call the getResult() method from a builder instance. (See the Client listing above.)

The Concrete Builders

Even the concrete builders seem fairly abstract in this design. All they do is pass strings to the product for construction via the helper classes. However, the concrete builders, like just about everything else in a design pattern, are communication nodes. Remember, in OO,

a process is expressed as a succession of messages across objects

So what we’re seeing is the process of messages passed through the classes (objects). In the concrete builders, the content of the messages is carved in the stone of literal values. This may bring up some short with the query, Why didn’t you put them in variables? First, keep in mind that literals are assigned somewhere, and all that’s being done is placing the assignment in the concrete builders. Second, adding variables would only back up the assignment of the literals and add unnecessary code.

Other than assembling the product, the concrete builders are also returning a completed product. Given the complex nature of the building process, one might wonder whether the job gets done by the time its ready to return something. The process returns the Product object in some shape, but not necessarily the one you’re expecting. After all, this builder is accessing video, loading text, graphics, and SWF files. What if the FMS server isn’t quite awake? All kinds of things have to happen, and I’ve found that on initial tests some parts get left behind or are a bit late in getting in place. Preloaders give me the creeps because they imply you haven’t paid attention to the size of your files and the user is going to be kept waiting. For a prime time version of this application, you might want to think about some kind of notification that the product is fully assembled and perhaps a” be with you in a jiffy” note to the user who’s waiting for the product.

I placed the finished product on three different servers and got three different reactions. On my LAN, the San Francisco video (plain vanilla FLV running on Flash Media Server) works perfectly, but when I posted it on a different remote Flash Media Server, it did a quick entrance and exit. One server did not play the progressive download, while another played the progressive download but did not put in the background. Click the Play button and see what you get.

The following three listings show the concrete builders in the design:

Sri Lanka is the first destination. The video uses a progressive download, and in case you can’t work with Flash Media Server 3.5.2 (or later), you can change all of the concrete builders to work with progressive downloads as well. All you have to do is the use the “.flv” suffix. (See how easy it is to change things using a Builder pattern?)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

package
{
	public class ConcreteBuilder1 implements IBuilder
	{
		private var product:Product = new Product();
 
		public function buildHotel():void
		{
			product.assemble("srilanka/hotel.jpg");
		}
 
		public function buildSight():void
		{
			product.assemble("srilanka/sriLankaBG.swf");
		}
 
		public function buildEvent():void
		{
			product.assemble("srilanka/sriLanka.flv");
		}
 
		public function buildWriteUp():void
		{
			product.assemble("srilanka/sriLanka.txt");
		}
 
		public function getResult():Product
		{
			return product;
		}
	}
}

Figure 2 shows what the builder generates for this concrete builder:

Figure 2: Sri Lanka is colorful, and the background reflects this character

The second destination is San Francisco. Everything is pretty much the same except the video file is being streamed from Flash Media Server. If you want to run an FLV file named sanFrancisco using progressive download, just change the value to “sanFrancisco.flv” and any local folder in use.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

package
{
	public class ConcreteBuilder2 implements IBuilder
	{
		private var product:Product = new Product();
 
		public function buildHotel():void
		{
			product.assemble("sf/hotel.jpg");
		}
 
		public function buildSight():void
		{
			product.assemble("sf/sfBG.swf");
		}
 
		public function buildEvent():void
		{
			product.assemble("sanFrancisco");
		}
 
		public function buildWriteUp():void
		{
			product.assemble("sf/sf.txt");
		}
		public function getResult():Product
		{
			return product;
		}
	}
}

Coming up with a color combination for San Francisco was a little tricky, and I finally settled on one I found at Kuler. (In fact I got all of my color combinations there.) Figure 3 shows the results:

Figure 3: San Francisco's Fairmont Hotel's lobby is featured

The third concrete builder is built around a visit to Prague, Czech Republic I took. The color combination for the background is named on Kuler, Mala Strana (little district) where I happened to stay on my visit. The video is an HD one taken with a Mino HD Flip camera and rendered into H.264 format—f4v. You will notice that the buildEvent() method passes a literal with a long reference—”mp4:pragueFolk.f4v”. Unfortunately, H.264 format is not available for progressive download, but you can substitute any .flv file you want.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

package
{
 
	public class ConcreteBuilder3 implements IBuilder
	{
		private var product:Product = new Product();
 
		public function buildHotel():void
		{
			//graphic
			product.assemble("prague/hotel.jpg");
		}
 
		public function buildSight():void
		{
			//swf file
			product.assemble("prague/pragueBG.swf");
		}
 
		public function buildEvent():void
		{
			//video
			product.assemble("mp4:pragueFolk.f4v");
		}
 
		public function buildWriteUp():void
		{
			//import text
			product.assemble("prague/prague.txt");
		}
 
		public function getResult():Product
		{
			return product;
		}
	}
}

Figure 4 shows the combined elements for this third rendered build:

Figure 4: Prague's flavor is captured in text, image and video.

While the classes that make up the concrete builders are very similar, you can see that the exact nature of the builds and their content is quite different.

The Product Class and Helper Classes

All of the heavy lifting is done by the Product class and its helpers. (Think of the Product class as Santa Claus and the helpers as his elves.) As you can see in the Product class listing, the object uses an array to assemble the product. Then it goes through the array using a switch statement to create the requested element using the helper classes (ImageLoader, EventPlayer and TextLoader). Once it is finished, it empties the array (features.length=0).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

package
{
	import flash.display.Sprite;
	public class Product extends Sprite
	{
		private var features:Array=new Array();
		private var ep:EventPlayer;
		private var tl:TextLoader;
		private var il:ImageLoader;
		private var bg:ImageLoader;
		private var productHolder:Sprite=new Sprite();
 
		public function assemble(...rest ):void
		{
			features.push(rest);
		}
 
		public function disclose():void
		{
			cleanProduct();
			addChild(productHolder);
 
			var counter:uint=0;
 
			for each (var facet:Array in features)
			{
				switch (counter)
				{
					//Graphic
					case 0 :
						il=new ImageLoader(String(facet));
						productHolder.addChild(il);
						il.x=410,il.y=10;
						break;
					//Swf
					case 1 :
						bg=new ImageLoader(String(facet));
						productHolder.addChildAt(bg,0);
						break;
					//Video
					case 2 :
						ep=new EventPlayer(String(facet));
						productHolder.addChild(ep);
						break;
					//Text write-up
					case 3 :
						tl=new TextLoader(String(facet));
						productHolder.addChild(tl);
						break;
				}
				counter++;
			}
 
			features.length=0;
		}
 
		private function cleanProduct():void
		{
			while (productHolder.numChildren>0)
			{
				productHolder.removeChildAt(0);
			}
		}
	}
}

The Product class has to deal with placing materials on the display list and removing them once its finished. I found that the easiest way to handle the DisplayObject was to create a sprite to act as a holder. Before adding new materials to the display list, everything in the holder is removed using the code:

while (productHolder.numChildren>0)
{
productHolder.removeChildAt(0);
}

I learned that if I used that code on the root display, it’d wipe out everything; however, it is a handy tool for cleaning up. So you can use it to clean up the just the holder sprite.

Loading images (jpg, png, gif) and compiled Flash (.swf) files use identical formats. So the ImageLoader helper could be used for both loading the image of the hotel and the background. Note, however, that the background has to be slipped beneath everything else, and so it was placed at the lowest level (0) using addChildAt(). The following script shows the code for this hard working helper:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

package
{
	import flash.display.Loader;
	import flash.net.URLRequest;
	import flash.display.Sprite;
	import flash.display.Loader;
 
	public class ImageLoader extends Sprite
	{
		private var imgNow:String;
		private var loader:Loader=new Loader();
 
		public function ImageLoader(img:String)
		{
			imgNow=img;
			var url:URLRequest=new URLRequest(imgNow);
			loader.load(url);
			addChild(loader);
		}
	}
}

As you can see, the ImageLoader class doesn’t take much code. (You may have noticed that the Client uses it to load the initial background.) It’s small but mighty!

The EventPlayer class is essentially a video player class. It accommodates both streaming via Flash Media Player and progressive downloads. Basically, if it is passed a url with the “.flv” extension, it plays the video as a progressive download; otherwise, it plays the video using Flash Media Server.

As for placing the video object on the display list, the video object is removed from the list by itself. When the video ends, it tidies up after itself. The following listing shows this somewhat complex helper class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

package
{
	import flash.net.NetConnection;
	import flash.net.NetStream;
	import flash.display.Sprite;
	import flash.media.Video;
	import flash.events.NetStatusEvent;
 
	public class EventPlayer extends Sprite
	{
		private var vid:Video=new Video();
		private var nc:NetConnection=new NetConnection();
		private var ns:NetStream;
		private var rtmpNow:String="rtmpe://192.168.0.11/context/events";
		private var goodConnect:Boolean;
		private var theEnd:Boolean;
		private var metaSniffer:Object=new Object();
		private var flv:String;
		private var vidBed:Sprite=new Sprite();
 
		public function EventPlayer(flvNow:String)
		{
			addChild(vidBed);
			vidBed.addChild(vid);
			flv=flvNow;
 
			nc.addEventListener(NetStatusEvent.NET_STATUS,checkConnection);
			if (flv.substring(flv.length-4)!=".flv")
			{
				nc.connect(rtmpNow);
			}
			else
			{
				nc.connect(null);
				ns=new NetStream(nc);
				vid.x=60,vid.y=320;
				ns.play(flv);
				vid.attachNetStream(ns);
				ns.client=metaSniffer;
				metaSniffer.onMetaData=getMeta;
				ns.addEventListener(NetStatusEvent.NET_STATUS,checkComplete);
			}
		}
 
		private function checkConnection(e:NetStatusEvent):void
		{
			goodConnect=e.info.code=="NetConnection.Connect.Success";
			if (goodConnect)
			{
				ns=new NetStream(nc);
				vid.x=60,vid.y=320;
				ns.play(flv);
				vid.attachNetStream(ns);
 
				ns.client=metaSniffer;
				metaSniffer.onMetaData=getMeta;
 
				ns.addEventListener(NetStatusEvent.NET_STATUS,checkComplete);
 
			}
			else
			{
				//Add Error Handler
			}
		}
 
		private function getMeta(mdata:Object):void
		{
			if (mdata.width<=720)
			{
				vid.width=mdata.width/2;
				vid.height=mdata.height/2;
			}
			else
			{
				vid.width=mdata.width/3;
				vid.height=mdata.height/3;
			}
		}
 
		private function checkComplete(e:NetStatusEvent):void
		{
			theEnd=e.info.code=="NetStream.Play.Stop";
			if (theEnd)
			{
				ns.close();
				vid.clear();
				removeChild(vidBed);
			}
		}
	}
}

The EventPlayer class also deals with videos of different sizes using the file’s own metadata. It looks at the width and height of the video and then decides whether to divide the width and height by 2 or 3. (Anyone who’d like to add a more sophisticated algorithm for this process is welcomed.)

The final helper class loads the text stored in an external text file. The operations are fairly straightforward for text loading. However, it does have a load-checker to seen when all of the text from the file has been passed to the URLLoader object (txtLoader) which is then passed to the text property of the TextField instance.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

package
{
	import flash.display.Sprite;
	import flash.text.TextField;
	import flash.text.TextFormat;
	import flash.net.URLLoader;
	import flash.net.URLRequest;
	import flash.events.Event;
 
	public class TextLoader extends Sprite
	{
		private var textContainer:Sprite=new Sprite();
		private var urlNow:URLRequest;
		private var txtLoader:URLLoader=new URLLoader();
		private var txtFld:TextField=new TextField();
		private var txtFormat:TextFormat=new TextFormat();
 
		public function TextLoader(textNow:String)
		{
			addChild(textContainer);
			urlNow=new URLRequest(textNow);
			txtLoader.addEventListener(Event.COMPLETE, addTxtFld);
			txtLoader.load(urlNow);
		}
 
		private function addTxtFld(e:Event):void
		{
			var loader:URLLoader=URLLoader(e.target);
			txtFormat=new  TextFormat();
			txtFormat.font="Verdana";
			txtFormat.size=11;
			txtFormat.color=0x000000;
			txtFld.defaultTextFormat=txtFormat;
			txtFld.multiline=true;
			txtFld.width=210;
			txtFld.height=250;
			txtFld.wordWrap=true;
			txtFld.x=163,txtFld.y=40;
			txtFld.text=loader.data;
			textContainer.addChild(txtFld);
		}
	}
}

When a new vacation destination is called, the text is removed by the Product class. In this way, you do not get text stacking on top of itself.

Do Something

I am hoping that some readers will add another vacation destination to better understand how the Builder pattern works and to see how easy it is to build a relatively complex object. All adding a new destination requires is building another concrete builder by copying and pasting one of the existing ones and adding the required text literals. Create a .swf file with a background for your new vacation and place it where it can be accessed from a Web server. Add a button to the Client and the sequence of steps used for the first three; and you’re done.

In both our book and on this blog, Chandima and I have tried to clarify and simplify ActionScript 3.0 Design Patterns and yet keep them accurate and, whenever possible, practical. After reviewing many, many Builder examples, I was surprised to find pieces missing in several instances, and while the examples may have combined elements (such as the Client and Director); others simply left out crucial components. (Who could forget bad, bad Leroy Brown who looked like a jigsaw puzzle with a couple of pieces gone?)

Given this state of affairs, it occurred to me that this pattern might be tricky; however, after working up an example, it turns out to be relatively simple and useful. Nevertheless, it’s not quite as simple as some, such as the Strategy or Factory Method, and so the discussion of the Builder is in two parts. This first part provides a clear overview so that you can easily see how the different components work together and starts a practical project., The second part (in a separate post) removes the abstract trace statements and displays actual content on the stage in a useful way. This will be to see if video, SWF, text, and images can be usefully integrated using the Builder.

Builder Overview

When you first look at the Builder class diagram shown in Figure 1, you might think it looks a lot like the Strategy pattern. Well, the class diagrams are similar, but the intent is very different. Also, you’ll find that the little Product class is hugely important.

Figure 1: Builder Class Diagram

The GoF summarize the intent of the Builder class as, [to] separate the construction of a complex object from its representation so that the same construction process can create different representations. Therein lies the problem. You can imagine the different ways this may play out. One way, which we’ve used in this initial example, is to use the Product class as a general clearinghouse for products with everything going to the same Product class. It “assembles” the results of the different operations from the concrete Builder classes and displays them. Another way to use the Product class is to create a different product class for each concrete Builder class. This latter technique is good when you want to use the Builder design pattern for building products based on the same interface but generating very different results.

In one creative Builder written in Java, the developer had a single Product class and then delegated the production to different concrete classes using aggregation from the Product class to the “helper” classes. It was an interesting design in that the differences between the concrete Builder classes was minor but each had a common task that required a hefty amount of work. The solution, at first glance, seemed to be to create a separate Product class for each of the concrete Builder classes (as did GoF in one of their examples) but since the building work is not done in the Product class, he needed to add the helper classes.

To get a better picture of the Builder design pattern, the following shows the task performed by each participant in a project that builds different vacations. Each vacation shows a hotel, a major sight (e.g., Eiffel Tower), an event (e.g., Carnival) worth seeing in the selected location, and a general write-up.

Builder: The Builder is the abstract interface. In this first example, I used an interface rather than an abstract class. The operations in the Builder are the required tasks for building the different parts of the Product object. In this example, the main tasks are:

• buildHotel
• buildSight
• buildEvent
• buildWriteUp

I used the getResult() name that GoF show in the Class diagram as part of a ConcreteBuilder, but since the requests in the Client are typed to the interface (IBuilder), I needed to place it in the Builder itself.

ConcreteBuilder: Each ConcreteBuilder class implements the operations in the Builder interface, builds the product and delivers the assembled results to the Product. As noted, the getResult() retrieves the product. Because in this example, all concrete builders use the same product, it uses the same retrieval operation. However, if each built significantly different products, each of the retrieval operations would have to be unique.

Director: Using the Builder interface, the Director constructs the desired object. For example, the following are two used in our example:
       builder.buildHotel();
       builder.buildSight();
The Director holds an aggregate relation to the IBuilder using an IBuilder instance in a function’s parameter.

Product: The Product class is used to represent the building process. In this example, it does so by pushing elements into a Vector (or Array) object. It may include classes that define the constituent parts for assembling the parts into the final result. So you can either have multiple ConcreteBuilders instantiate the same Product object or different ones.

Composing Video, SWF, Images, and Text

In developing this application, I was thinking of a travel site that would include the following:

• An SWF file showing a hotel
• A graphic file showing a building or other sight
• A video of an event
• Text write-up describing the vacation destination

In Part II of this post I plan to fill in the current trace statements with the above objects. Because every vacation location will have each of the objects, I cannot see using separate Product classes for each of the vacation sites; therefore, it will have a similar structure as this current example.

A Builder Vacation Site

In order to provide a visual image of what this particular design pattern does, Figure 2 shows the user interface along with the output via trace statements. (If you use Kuler, either the one built into Flash CS4 or at the Adobe Kuler site, you will be happy to know that they have a color theme named Builder that has been employed in the example.)

Figure 2: Builder example with UI, background and output

The four output lines generated by selecting one of the buttons conforms to the four Builder functions (less the getResult() method). With Figure 2 in mind, we can now dissect the program.

The Client

The Client class is not shown in the class diagram, and so we need to consider where it directs its requests. According to GoF, the client creates the Director object and configures it with the desired Builder object. You will see this operation in the following format:

director.construct(trip1);
srilanka = trip1.getResult(); //srilanka = Product instance
srilanka.disclose();

The director is a Director instance and trip1 is a Builder instance typed to the IBuilder interface. In this implementation, each “trip” refers to one of the three vacation destinations—Sri Lanka, San Francisco or Prague. When one of the UI buttons is pressed, an event handler simply generates the necessary output through the Director’s construct() method. Then, a Product instance, named after the vacation destination, is assigned the return value of the particular ConcreteBuilder and then the Product disclose() method displays the information as a trace output.

The following code shows the entire Client listing:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

//Client
package
{
	import flash.display.Sprite;
	import fl.controls.Button;
	import flash.events.MouseEvent;
 
	public class Client extends Sprite
	{
		private var director:Director = new Director();
		//Concrete builders
		private var trip1:IBuilder = new ConcreteBuilder1();
		private var trip2:IBuilder = new ConcreteBuilder2();
		private var trip3:IBuilder = new ConcreteBuilder3();
		//Products
		private var srilanka:Product;
		private var sanfrancisco:Product;
		private var prague:Product;
		//Buttons
		private var btn1:Button=new Button();
		private var btn2:Button=new Button();
		private var btn3:Button=new Button();
 
		public function Client()
		{
			setButtons();
		}
 
		private function setButtons():void
		{
			btn1.x = 16;
			btn1.y = 64;
			btn1.label = "Sri Lanka";
			btn1.addEventListener(MouseEvent.CLICK, goSriLanka);
			addChild(btn1);
 
			btn2.x = 16;
			btn2.y = 96;
			btn2.label = "San Francisco";
			btn2.addEventListener(MouseEvent.CLICK, goSanFrancisco);
			addChild(btn2);
 
			btn3.x = 16;
			btn3.y = 128;
			btn3.label = "Prague";
			btn3.addEventListener(MouseEvent.CLICK, goPrague);
			addChild(btn3);
		}
 
		private function goSriLanka(e:MouseEvent):void
		{
			director.construct(trip1);
			srilanka = trip1.getResult();
			srilanka.disclose();
		}
 
		private function goSanFrancisco(e:MouseEvent):void
		{
			director.construct(trip2);
			sanfrancisco = trip2.getResult();
			sanfrancisco.disclose();
		}
 
		private function goPrague(e:MouseEvent):void
		{
			director.construct(trip3);
			prague = trip3.getResult();
			prague.disclose();
		}
	}
}

Now that you can see the request structure, we can look at the main participants in the pattern.

Director

The Director class is a concrete class with the responsibility of constructing an object. Using its sole method construct() it uses a Builder (IBuilder) reference to create the necessary parts that make up the product.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

//Director
package
{
	public class Director
	{
		public function construct(builder:IBuilder):void
		{
			builder.buildHotel();
			builder.buildSight();
			builder.buildEvent();
			builder.buildWriteUp();
		}
	}
}

The Director acts to create an aggregate relationship with the Builder interface (IBuilder) and allows the Client to request a product be built. In this way it maintains a loose relationship between its request and the concrete builders. This reduces dependencies thereby providing less problems changing or adding concrete builders and the products they build.

Builder Interface

I always feel more comfortable using ActionScript 3.0 interfaces than the ersatz abstract classes even though I sometimes miss the advantages of abstract classes. However, for this example, the ActionScript 3.0 interface statement is just what I need. Like most interfaces, all the IBuilder interface does is to provide abstract operations to be used in implementations. In the case of the Builder design pattern, these operations specify which parts of the Product will be built.

1
2
3
4
5
6
7
8
9
10
11
12

//Builder Interface
package
{
	interface IBuilder
	{
		function buildHotel():void;
		function buildSight():void;
		function buildEvent():void;
		function buildWriteUp():void;
		function getResult():Product;
	}
}

As noted, the pattern’s class diagram does not show the getResult() method in the Builder interface , but it is necessary if the Client types to the Builder (IBuilder) interface.

Concrete Builders: The Patterns Payoff

Once the Builder interface has been established, adding or changing the concrete part builders is a piece of cake. For example, I could add as many concrete builders for different vacation destinations as I want. Likewise, I could change the parts to be “assembled” in any of the concrete builder classes. In this particular example, it’s even easier because the only thing that has to be changed is the content in the Product.assemble() operation. The following make up the three concrete builders:

Sri Lanka

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

//ConcreteBuilder1
package
{
	public class ConcreteBuilder1 implements IBuilder
	{
		private var product:Product = new Product();
 
		public function buildHotel():void
		{
			product.assemble("Mt. Lavinia Hotel is right on the beach");
		}
 
		public function buildSight():void
		{
			product.assemble("The Temple of Buddha's tooth in Kandy is beautiful");
		}
 
		public function buildEvent():void
		{
			product.assemble("Esala Perahera fesitval features elephants");
		}
 
		public function buildWriteUp():void
		{
			product.assemble("Let me tell you about Sri Lanka...");
		}
 
		public function getResult():Product
		{
			return product;
		}
	}
}

San Francisco

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

//ConcreteBuilder2
package
{
	public class ConcreteBuilder2 implements IBuilder
	{
		private var product:Product = new Product();
 
		public function buildHotel():void
		{
			product.assemble("Fairmont Hotel is a landmark in San Francisco");
		}
 
		public function buildSight():void
		{
			product.assemble("Take a drive across Golden Gate Bridge");
		}
 
		public function buildEvent():void
		{
			product.assemble("Don't miss the Carnival in May");
		}
 
		public function buildWriteUp():void
		{
			product.assemble("Let me tell you about San Francisco...");
		}
		public function getResult():Product
		{
			return product;
		}
	}
}

Prague

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

//ConcreteBuilder3
package
{
	public class ConcreteBuilder3 implements IBuilder
	{
		private var product:Product = new Product();
 
		public function buildHotel():void
		{
			product.assemble("Hotel Tyl -- small but nice");
		}
 
		public function buildSight():void
		{
			product.assemble("Visit the medieval Prague Castle");
		}
 
		public function buildEvent():void
		{
			product.assemble("The Prague International Jazz Festival is a treat");
		}
 
		public function buildWriteUp():void
		{
			product.assemble("Let me tell you about Prague...");
		}
 
		public function getResult():Product
		{
			return product;
		}
	}
}

With the parts assembly completed, we turn next to the final product—the Product Class.

Product

As we’ve discussed, the Product class represents the assembled parts created by the builders. In this example, all of the parts are pushed as strings onto a Vector object (or Array). Then the final product is displayed through a disclose() method that sends the output using a trace statement.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

//Product
package
{
	public class Product
	{
		private var features:Vector.<string>  = new Vector.<string>();
		//If your version of Flex or Flash does not have Vector uncomment
		//the following line and comment out the Vector line
		//private var features:Array=new Array();
 
		public function assemble(aspect:String ):void
		{
			features.push(aspect);
		}
 
		public function disclose():void
		{
			for each (var facet:String in features)
			{
				trace(facet);
			}
			trace("");
 
			features.length=0;
		}
	}
}

Keeping in mind that the purpose of this first example is to see how the participants in a Builder work together, think of ways that this pattern could be applied to some of your own projects.

The Test is in Changing and Adding

This sample application ought to be a good one for changing and adding classes. Try adding another class for another city or country. You’ll have to make adjustments to the Client as well to select anything new that you add. Changing content in this particular application is simply a matter of changing the content of the text literals in the ConcreteBuilder classes.

As always, your comments and ideas are welcomed.