Recently, I’ve started a fairly large project in C# 3.0. As it happens, there came a point where I wanted to use a pattern similar to Bloch’s Builder. However, as anyone who tries to use this pattern in C# will quickly find out, Bloch’s Builder doesn’t translate perfectly to C#.

Here is how Bloch’s Builder looks in C# (with changes made only for syntax):

public class NutritionFacts
{
  public int ServingSize { get; private set; }
  public int Servings { get; private set; }
  public int Calories { get; private set; }
  ...
 
  public class Builder
  {
    private int ServingSize { get; set; }
    private int Servings { get; set; }
    private int Calories { get; set; }
 
    public Builder(int servingSize, int servings)
    {
      ServingSize = servingSize;
      Servings = servings;
    }
 
    public Builder Calories(int calories)
    { Calories = calories; return this; }
    ...
 
    public NutritionFacts Build()
    {
      return new NutritionFacts(this);
    }
  }
 
  private NuitritionFacts(Builder builder)
  {
    ServingSize = builder.ServingSize;
    Servings = builder.Servings;
    Calories = builder.Calories;
    ...
  }
}

If you try to compile that code, the C# compiler will complain, saying that it does not have permission to access the private members of the Builder class.

Then how come it worked in Java? The answer is that Java has a special rule that allows Java outer classes to access the private members of their inner classes. In C#, this rule does not exist, and thus C# outer classes cannot access the private members of C# inner classes.

Since Bloch’s Builder pattern doesn’t work in C#, the natural next question is: how do we make it work?

Approach 1: Make Builder Properties Public

The C# compiler tells us that it can’t compile because it doesn’t have permission to access private members of the nested Builder class. Thus, the most obvious solution to this is to make them public:

public class NutritionFacts
{ 
  ...
  public class Builder
  {
    public int ServingSize { get; set; }
    public int Servings { get; set; }
    public int Calories { get; set; }      
    ...
  }
  ...
}

This allows the code to compile, and we can use the Builder just as we used it in Java.

However there is one niggling concern: the C# Builder exposes getters in the Builder object. In the Java Builder, when we were constructing an object, we were only able to use methods that contributed to building the object. That is, the Java Builder doesn’t expose any getters. However, in the C# version, our API is polluted by unneeded getters. Let’s see if we can do better.

Approach 2: Build the object in the Builder

As we’ve already seen, C# does not permit outer classes to access the private members of inner classes. However, C# does let us access outer classes from inner classes. Since that’s the case, why don’t we invert the building procedure. That is, let’s build the object in the Builder, instead of in the class being built:

public class NutritionFacts
{
  public int ServingSize { get; private set; }
  public int Servings { get; private set; }
  public int Calories { get; private set; }
  ...
 
  public class Builder
  {    
    private int ServingSize { get; set; }
    private int Servings { get; set; }
    private int Calories { get; set; }
 
    public Builder(int servingSize, int servings)
    {
      ServingSize = servingSize;
      Servings = servings;
    }
 
    public Builder Calories(int calories)
    { Calories = calories; return this; }
    ...    
 
    public NutritionFacts Build()
    {
      return new NutritionFacts
      {
        ServingSize = ServingSize,
        Servings = Servings,
        Calories = Calories,
        ...       
      };
    }
  }
 
  private NuitritionFacts()
  { 
    // Intentionally empty.
  }
}

That, to me, is the closest you can get to the Java pattern. From an API consumer’s point of view, it’ll look identical to a Java Builder.

Alternative Form

There is another alternative to the two C# Builders mentioned earlier in this article. As it stands, Bloch’s Builder can be used as a sort of prototype factory. You can configure the builder and then pump out instances of the class that have that configuration. However, if you’re using the Builder to make a single, immutable instance, a more efficient way would be to avoid copying the data first to the Builder and then to the new instance.

Here’s a version of the Builder (by Jon Skeet) that can be used only once, but avoids unnecessary data copying.

public class NutritionFacts
{
  public int ServingSize { get; private set; }
  public int Servings { get; private set; }
  public int Calories { get; private set; }
  ...
 
  public class Builder
  {       
    private NutritionFacts _facts = new NutritionFacts();
 
    public Builder(int servingSize, int servings)
    {
      _facts.ServingSize = servingSize;
      _facts.Servings = servings;
    }
 
    public Builder Calories(int calories)
    { _facts.Calories = calories; return this; }
    ...    
 
    public NutritionFacts Build()
    {
      var ret = facts;
 
      // Invalidates builder to maintain mutability.
      facts = null;
 
      return ret;
    }
  }
 
  private NuitritionFacts()
  { 
    // Intentionally empty.
  }
}

Some of the advantages of this pattern are:

• No data copying is required at build time. In other words, while you’re setting the properties, you’re doing so on the real object – you just can’t see it yet. This is similar to what StringBuilder does.
• The builder becomes invalid after calling Build() to guarantee immutability. This unfortunately means it can’t be used as a sort of “prototype” in the way that Bloch’s version can.

Conclusion

In this article we’ve looked at 3 different working C# implementations of Bloch’s Builder pattern. The first approach was a quick and dirty fix that got the job done. The second approach applied a bit more finesse and managed to keep the same API as the Java Builder. The final approach was more of a variation on the second approach, offering a more efficient implementation of the pattern if you’re not using the Builder as an object prototype factory.

What is WSDL?

Before we start, let’s talk a bit about what WSDL is. (Warning: I am very new to WSDL, SOAP and web services in general, so feel free to correct me if I get any of these details wrong).

WSDL stands for Web Service Description Language. As the name suggests, it is an XML language used for describing web services. By describe, I mean a WSDL file contains information like the functions that a client can call, and data types it uses, and what exceptions it might throw. This is useful for clients that might contact the web service. Exactly why that information is useful will become evident in examples below.

What is SOAP?

At one point, a long time ago, in a web far far away, SOAP stood for Simple Object Access Protocol. Now it stands for nothing. SOAP is a protocol for exchanging structured information on the web. Like WSDL, SOAP uses XML. In fact, SOAP is a protocol often used to exchange WSDL information, although one can also use straight HTTP to do it as well.

All we really need to know (right now) is that a SOAP library permits us to communicate with a WSDL web service that has SOAP bindings (which would be almost any we would encounter in the wild).

Which library/module to use?

In order to determine which library to use, I did some googling. What I found were two options: the NuSOAP library and the PHP SOAP module.

So which one should we use? I initially leaned towards NuSOAP due to the fact that it was an external library, and thus would probably work with almost any PHP installation. Unfortunately, after perusing the NuSOAP Sourceforge website, I noticed the library hadn’t been updated since 2005 (a bad sign). In fact, after further reading, I discovered that, as of PHP 5, the NuSOAP namespace also conflicted with the PHP SOAP module namespace (and hadn’t yet been fixed). As a result, I decided to go with the PHP SOAP module.

The Code

The first thing anyone needs to do when consuming a WSDL service with PHP is to create a new client object. By creating a client object, PHP basically reads the server’s WSDL file and determines which functions are available to us. A SoapClient is created using the following code:

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

<?php
  // The path to the WSDL web service.
  $wsdl = "http://path/to/webservice.wsdl";
 
  // The connection options.
  $options = array('features' => 
    SOAP_USE_XSI_ARRAY_TYPE + SOAP_SINGLE_ELEMENT_ARRAYS);
 
  // Create a new SoapClient.
  $client = new SoapClient($wsdl, $options);
  echo "SoapClient creation successful<br>\n";
?>

So what’s going on at line 7? Those two features are basically used to make the SoapClient act as we’d expect. For example, if you don’t include the SOAP_USE_XSI_ARRAY_TYPE feature, then you’ll find you get a lot of casting exceptions when dealing with a Java-based webservice that uses any complex data structures. If you don’t include the SOAP_USE_XSI_ARRAY_TYPE feature, then PHP will turn 1-element arrays return types into objects, which is not what you want 90% of the time and often gives confusing results.

Now let’s actually consume a web service. Let’s pretend we’re using the J2EE service provided by this article. Here are the contents of the WSDL file from that article:

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

<?xml version="1.0" encoding="UTF-8"?>
<definitions name="MyFirstService" targetNamespace="urn:Foo" xmlns:tns="urn:Foo"
    xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/">
  <types/>
  <message name="MathFace_add">
    <part name="int_1" type="xsd:int"/>
    <part name="int_2" type="xsd:int"/></message>
  <message name="MathFace_addResponse">
    <part name="result" type="xsd:int"/></message>
  <portType name="MathFace">
    <operation name="add" parameterOrder="int_1 int_2">
      <input message="tns:MathFace_add"/>
      <output message="tns:MathFace_addResponse"/>
    </operation>
  </portType>
  <binding name="MathFaceBinding" type="tns:MathFace">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="rpc"/>
    <operation name="add">
      <soap:operation soapAction=""/>
      <input>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
		    use="encoded" namespace="urn:Foo"/>
      </input>
      <output>
        <soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
		    use="encoded" namespace="urn:Foo"/>
      </output>
    </operation>
  </binding>
  <service name="MyFirstService">
    <port name="MathFacePort" binding="tns:MathFaceBinding">
      <soap:address location="http://localhost:8080/math-service/math"/>
    </port>
  </service>
</definitions>

What can we tell about the web service by looking at this file? Well the first thing you should notice is lines 12-14. In those lines, the web service defines an operation (“add”) that takes two arguments (“int_1 int_2″). As a result, we know that the web service exposes an add operation that takes two integer arguments. Let’s use that knowledge to invoke the add operation in PHP using the SOAP module:

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

<?php
  // The path to the WSDL web service.
  $wsdl = "http://localhost:8080/math-service/math?wsdl";
 
  // The connection options.
  $options = array('features' => 
    SOAP_USE_XSI_ARRAY_TYPE + SOAP_SINGLE_ELEMENT_ARRAYS);
 
  // Create a new SoapClient.
  $client = new SoapClient($wsdl, $options);
  echo "SoapClient creation successful<br>\n";
 
  // Call the add operation.
  $response = $client->add(2, 2);
 
  // This should print 4.
  echo $response . "<br>\n";
?>

How’d the PHP object $client know to have an add method? It simply read the WSDL file the same way we did, and realized that the web service exposed that operation.

As you can see, consuming a J2EE web service from a PHP client is not too complicated. Once you understand the rudiments of a WSDL file and the PHP SOAP module, calling remote functions becomes a snap.

Today, I’m going to take a look at an variety of programming tasks and show how they are done in both Java and VB.NET (the .NET 1.1 version). Since both these languages have differing feature sets, I’ll try to only use features that both the languages have, in order to compare them fairly. I know this might misrepresent the complexity of the languages, and I’m cool with that. The purpose of this post is merely to explore and discuss the syntax of each language.

Collections

Creating and manipulating collections is a common task in procedural programming languages, so let’s look at that first. Consider arrays. To make an array of 10 String objects in Java, I would do this:

final int ARRAY_LENGTH = 10;
String[] arr = new String[ARRAY_LENGTH];

In VB.NET, things get a bit more complicated, but for the most part, you’d do something like this:

Const ARRAY_LENGTH As Integer = 10
Dim arr(ARRAY_LENGTH - 1) As String

Woah, what? Why is it ARRAY_LENGTH – 1? That’s because VB.Net is an evolution of VB6, and in VB6, for reasons unknown, the value in the parenthesis is not the number of elements but instead the maximum index. There’s a second way to create arrays in VB.NET using anonymous arrays:

Dim arr() As String = New String() { "foo", "bar" }

You may also create arrays using anonymous arrays in Java:

String[] arr = new String[] { "foo", "bar" };

Now let’s look at something a bit more powerful: the ArrayList. Both Java and VB have a version of this class with more or less the same syntax. Let’s use them in a real world situation. Consider this task: We have an ArrayList with a bunch of Strings and we want to join them together using a comma. Here’s the code to do that in VB without using generics:

' Option Strict is On (as it should be).
Dim list As ArrayList = New ArrayList
list.Add("a")
list.Add("b")
list.Add("c")
 
' Create the comma-joined string.
Dim str As String = String.Join(",", _ 
    DirectCast(list.ToArray(GetType(String)), String()))

That’s quite a jumble at the end there. Let’s see we would do it in Java (again, without generics):

List list = new ArrayList();
list.add("a");
list.add("b");
list.add("c");
 
// Create the comma-joined string.  Let's assume that we've 
// created a method called join(String str, String[] strList) 
// that acts the same as .NET's String.Join().
String str = join(",", (String[]) list.toArray(new String[0]));

(Aside: Anyone familiar with generics is probably beating their head against their desk. This example is just screaming for it. I’ll include the generified version of the Java example at the end for the curious.)

Same problem in Java. Converting from an ArrayList (or any Collection for that matter) does not look pretty (and is somewhat complicated for a novice programmer), even though it doesn’t seem like it’s a lot of ask. We have a collection of things, and we want to put them into an array, which is a very basic type of a collection. What’s the problem?

Basically, it has to do with the programming language not knowing what’s in the ArrayList. If we just wanted to convert to an array of objects, that’s no problem:

// Imagine we still have the "list" object 
// from the previous example.
Object[] objArray = list.toArray();

This works because the programming language can be sure that all of the items in the ArrayList are at least Objects. Unfortunately, in most cases, that’s not especially helpful. Fortunately, both these languages have a solution to the problem and that’s telling the programming language that the ArrayList is an ArrayList of Strings. The technology that does that is called generic programming.

That’s it for today. In part 2, we’ll delve deeper into the wordiness of VB.NET and how it drives you nuts if you program with it on a regular basis. Here’s the generified version of the Java program for the keeners:

List<String> list = new ArrayList<String>();
list.add("a");
list.add("b");
list.add("c");
 
// Create the comma-joined string.  Let's assume that we've 
// created a method called join(String str, String[] strList) 
// that acts the same as .NET's String.Join().
String str = join(",", list.toArray());