The links for downloading code should now be working again.

Apologies to those of you trying to download code. I am having some issues with Plusnet. I will try to resolve these as soon as possible.

Introduction

Part 23 and part 24 of this series of articles described the Model-View-Presenter pattern.

This article explains how the Smart Client Software Factory supports this pattern by generating appropriate classes.

Part 26 of this series of articles will show how to use the generated classes in more detail.

Guidance Automation Packages in the Smart Client Software Factory

We saw how we could use the Smart Client Application Guidance Automation Package to set up a Smart Client Application in part 18. We can also set up a Model-View-Presenter pattern in a Smart Client application using another of the Guidance Automation Packages.

This will only work in an existing Smart Client Application.

Running the Model-View-Presenter Package

To use the Guidance Automation Package we right-click in Solution Explorer on a project or folder where we want to run the package. It is intended that we do this in the Views folder in a business module. On the right-click menu we select ‘Smart Client Factory/Add View (with presenter)’. We get a configuration screen that lets us name our view, and also lets us put the classes that get created into a folder. For the purposes of this example we name our view ‘Test’, and check the checkbox that says we do want to create a folder for the view.

When we click ‘Finish’ we get three classes and a TestView folder as below:

Classes Created

1. TestView
   This is (obviously) our View class. It is intended that this contain the auto-generated code to display the View. As discussed in the previous articles any complex view logic will not go into this class, but will go into the Presenter.
2. TestViewPresenter
   This is our Presenter class. As discussed in previous articles this should contain logic to deal with user events. It should also contain any complex view logic, and should directly update the View with the results of an view logic calculations. It has access to the View class via an interface.
3. ITestView
   This is the interface that the View implements. The Presenter can only update the View through this interface.

Diagram

In terms of the diagrams shown in parts 23 and 24 this looks as below. Remember that we may or may not have arrows between the Model and the View depending on whether we are using the active View or passive View version of Model-View-Presenter:

Where’s the Model?

The Guidance Automation package does not set up a Model class for us. As we have seen, the Model has no direct references to a View/Presenter pair (it raises events), and there may be multiple View/Presenter pairs for one Model. Further the Model would not usually be in the same folder, or even in the same component, as our View and Presenter.

For these reasons we are expected to set up our Model classes separately by hand.

Note that the Presenter (and the View as well if we are using the active View pattern) will have a direct reference to the Model. We will have to add these references manually.

Active and Passive View: a Quick Recap

Remember that in Model-View-Presenter the Presenter updates the View via an interface. We can set this up so only the Presenter is allowed to update the View. This is the ‘passive View’ pattern. We can also set this up so that the Presenter can update the View in complex cases, but the View can also update itself (in response to an event or user request) in simple cases. This is the ‘active View’ pattern.

Active and Passive View: Which Should We Use?

The pattern described in the SCSF documentation is the passive View: the documentation implies that all updates to the View should be done by the Presenter.

However there is nothing to stop us using the active View pattern with the classes generated by the Guidance Automation Package. We can add code to update the View wherever we like. In fact I would recommend using active View in simple cases: passive View should only be used where we are putting too much logic into the View class.

Should We Use Model-View-Presenter for Every Screen? A Personal View

Let me also reiterate a point made in part 24. It’s easy to get obsessive about the use of patterns and use them everywhere without thinking. My personal opinion is that we should only use the full Model-View-Presenter pattern where we have a complex screen that will benefit from the separation of the View and Presenter classes. For very basic screens the pattern is really too complex to give us benefit. In simple cases I think it is fine to put event handling and screen update logic directly behind the screen.

Note that I don’t think this applies to the use of the Model. We should always separate out the business logic from our screens into separate classes (this is what Martin Fowler calls ‘Separated Presentation’). However, we frequently have screens that don’t show any business logic or business data, so we may not need a Model class either.

For example an About screen that just shows the system name and version won’t need separate View and Presenter classes, and probably won’t need anything in a Model class either.

Equally a screen that shows a read-only grid of currencies used in a trading system probably doesn’t need separate View and Presenter classes. In this case the currencies themselves should be in a Model class so that other screens can access them.

Implementation Details: What We’d Expect

If we examine the diagram above, we expect the Presenter to have a data member with type of our ITestView interface that it will use to access the View. We expect the View to implement the ITestView interface to allow this. We further expect the View to have a direct reference to the Presenter class (a data member), which it will use to invoke code relating to user events. We’d probably expect both the View and the Presenter classes to be created the first time the View is needed.

Implementation Details: the Base Presenter Class

The actual details of the implementation of the Presenter are a little unusual.

If we look at the code generated by the Guidance Automation Package we see that the TestViewPresenter above has been given its core functionality by inheriting from an abstract Presenter<TView> class. Remember that the generic ‘TView’ simply lets us provide a type whenever we use the Presenter class. Here we inherit from Presenter, and provide the type when we inherit:

    public partial class TestViewPresenter : Presenter<ITestView>
    {

This allows the base Presenter class to have a data member of type ITestView (which is what we expect), rather than it being directly in the TestViewPresenter class. Note that the base Presenter is in the Infrastructure.Interface project (which is one of the reasons why we have to use this pattern in a Smart Client application).

The base Presenter class exposes our ITestView data member publicly, contains a reference to our WorkItem, and has disposal code and a CloseView method. It also has virtual OnViewReady and OnViewSet methods. These get called when you’d expect from the name and let us respond at the appropriate times by overriding the methods in our TestViewPresenter class.

All the above functionality in the base Presenter class means that the derived TestViewPresenter class is basically empty when it is created. It is up to us to put logic in there to handle user events and complex view logic.

The TestView class is a normal user control. It implements ITestView and contains a reference to the TestViewPresenter as we’d expect. It also calls OnViewReady as appropriate (in the OnLoad event of the user control). Again other than this TestView is also basically empty.

Conclusion

This article has shown us how to set up Model-View-Presenter classes using the Smart Client Software Factory, and discussed some issues surrounding it.

Part 26 of this series of articles will show how to use these classes in practice, providing code examples.

Introduction

Part 23 of this series of articles described the basic Model-View-Presenter pattern (MVP).

This article examines the Model-View-Presenter pattern in more detail. It describes some variations on the basic pattern, and looks at the advantages and disadvantages of using the pattern.

Part 25 of this series of articles will examine how the Model-View-Controller pattern is implemented in the Smart Client Software Factory (SCSF).

Can the View Update Itself? Active View versus Passive View

The version of Model-View-Presenter described in part 23 has an ‘active View’. This means that the View can update itself directly from the Model (arrows C and D on the diagram in the article). As described in part 23, the View can also be updated by the Presenter.

An alternative to this is what Martin Fowler calls the ‘passive View’. Here the View cannot update itself directly from the Model. The only way the View can be updated is via the Presenter. This is the pattern that the Microsoft SCSF documentation describes as Model-View-Presenter.

Diagrammatically this looks as below. It’s identical to the diagram in part 23 except that there are no arrows between the Model and the View:

The passive View design leads to more code in the Presenter and more code in general as the View now has to expose everything that can be updated on its interface, and the Presenter has to be coded to update it appropriately. However, this is arguably a less complicated design than the original active View in part 23.

Does the View Update Automatically? Active Model-View-Presenter versus Passive Model-View-Presenter

As with Model-View-Controller we have a distinction between an ‘active’ and a ‘passive’ design overall (see the section ‘Active and Passive MVC’ in part 22). Model-View-Presenter as described above in part 23 is ‘active’ Model-View-Presenter. This means that if the Model changes all Views will be updated automatically via the eventing mechanism. These events may be sunk in the Presenter or the View.

It is also possible to set up ‘passive’ Model-View-Presenter. This is a slightly simpler pattern where the Model does not raise an event when it changes. This means the View is not updated ‘automatically’. Instead the View is updated when the user next requests it (by pressing a ‘Refresh’ button for instance). At this time either the View or the Presenter will go to the Model to get the new data.

Advantages of Model-View-Presenter

As with Model-View-Controller, Model-View-Presenter has the advantage that it clarifies the structure of our user interface code and can make it easier to maintain. Not only do we have our data taken out of the View and put into the Model, but also almost all complex screen logic will now reside in the Presenter.

This solves the problems with more traditional user interface designs as described in the last few articles. However, it comes at the cost of some complexity.

Since we now have almost no code in our View apart from screen drawing code Model-View-Presenter also makes it theoretically much easier to replace user interface components (user controls, whole screens, or even the whole user interface (Windows Forms to WPF for example)).

In addition unit testing the user interface becomes much easier as we can test the logic by just testing the Presenter. However see part 23 for some comments on whether this is strictly necessary.

Disadvantages of Model-View-Presenter

The disadvantages of Model-View-Presenter are similar to the disadvantages of Model-View-Controller as described in part 22:

• The pattern is complex and may be unnecessary for simple screens.
• The pattern is one more thing to learn for busy developers: there’s some overhead.
• It can be hard to debug events being fired in active Model-View-Presenter.
• The ‘Passive View’ version of Model-View-Presenter can lead to a certain amount of boilerplate code having to be written to get the interface into the View to work.

My personal view is that even if you think this is a useful pattern (and it is) you shouldn’t use it indiscriminately on every screen in your application. You should use it where you have reasonably complex logic which will benefit from splitting the user interface classes in this way.

User Events and View Logic Combined in the Presenter

One thing that seems a bit odd with Model-View-Presenter is that we have factored both the responses to user input events and what I’m calling the ‘complex view logic’ into our Presenter. At first glance these seem to be slightly different things: perhaps we should have separate classes for each? Perhaps we need a Presenter and a Controller?

One reason for not doing this is that our user interface is getting very complicated if we have both Presenter and Controller.

Also, in the passive version of Model-View-Presenter we may want the user event itself to call the complex view logic and to directly update the View. This means that the code to handle the user event also needs to contain the view logic. It can’t do this if we have separate classes for the two pieces of functionality. In this case it makes more sense if we only have one class.

However, splitting the Presenter into two classes may be a valid pattern in active Model-View-Presenter. Here the Model will be updated in response to a user event by the Presenter. The Model will then raise an event to the Presenters telling them to update the View for complex view logic. The user event and complex view logic are thus separate in the Presenter and could be split into separate classes. We would probably only want to do this in very complex screens.

Model-View-Controller and Model-View-Presenter Confusion

As Martin Fowler points out, there’s a lot of confusion over what Model-View-Controller is. As already discussed, this arises because it doesn’t really apply to modern user interface programming languages in its purest Smalltalk form.

Equally there seems to be a lot of confusion over what Model-View-Presenter is. Martin Fowler currently calls the basic MVP pattern that I describe in part 23 ‘Supervising Controller’. He calls the amended version presented in this article ‘Passive View’ (as does this article).

I’m not quite sure why Mr Fowler calls the basic Model-View-Presenter pattern ‘Supervising Controller’ and not ‘Supervising Presenter’. It seems to me that the key difference between Model-View-Controller and Model-View-Presenter is that the Presenter in Model-View-Presenter can update the View directly. This is not permitted in Model-View-Controller; here the View updates itself from the Model. In the ‘Supervising Controller’ the Presenter/Controller can update the View directly.

Having said that I’m not sure that Mr Fowler would recognize the pattern described in part 22 as Model-View-Controller: this is closer to Model-View-Presenter as he describes it. As I mention in part 22 the pattern described is not ‘pure’ Model-View-Controller because the user events are initially sunk in the View (which is normal with modern UI widgets) and because there’s only one Controller and View per screen, rather than one per widget as in pure Model-View-Controller.

Finally note that I have adopted the ‘Passive View’ nomenclature in this article. However personally I think calling this pattern ‘Passive View’ adds to the confusion surrounding Model-View-Presenter. We already have the concept of active/passive Model-View-Controller and Model-View-Presenter as a whole, ‘active’ being the case where all Views get updated automatically on a change in the Model, ‘passive’ being where they have to update themselves. This is easily confused with an active/passive View distinction. Here an ‘active’ View is one that can update itself from the Model, whether automatically or not.

Conclusion

We have now covered quite a lot of the theory behind both Model-View-Controller and Model-View-Presenter.

Part 25 of this series of articles will show how we can use Model-View-Presenter in the CAB/SCSF using an SCSF Guidance Automation Pattern.

References

The two flavours of Model-View-Presenter described by Martin Fowler
http://www.martinfowler.com/eaaDev/PassiveScreen.html (‘Passive View’ in fact)
http://www.martinfowler.com/eaaDev/SupervisingPresenter.html (‘Supervising Controller’ in fact)

Martin Fowler overview of GUI Architectures, including Model-View-Controller and Model-View-Presenter
http://www.martinfowler.com/eaaDev/uiArchs.html

Good explanation of Model-View-Presenter, Passive View and Supervising Controller on CodePlex
http://www.codeplex.com/websf/Wiki/View.aspx?title=ModelViewPresenterPatternDescription&referringTitle=MVPDocumentation

MSDN Article with code example (although the article is a little confusing)
http://msdn.microsoft.com/msdnmag/issues/06/08/DesignPatterns/

See also the page in the Smart Client Software Factory documentation on Model-View-Presenter
http://www.codeplex.com/smartclient/Release/ProjectReleases.aspx?ReleaseId=5027

Introduction

Part 22 of this series of articles looked at the Model-View-Controller pattern and discussed how it is one way of structuring a user interface to avoid having too much code behind a screen.

This article will examine some of the shortcomings of Model-View-Controller, and describe an alternative, which is Model-View-Presenter.

Part 24 of this series of articles will then briefly examine some variations on the basic Model-View-Presenter pattern described here, and look at the advantages and disadvantages of the pattern.

Part 25 of this series of articles will look at the support that CAB/SCSF gives us for the Model-View-Presenter pattern.

Model-View-Controller Problems

There are a couple of user interface scenarios that are difficult to handle with the Model-View-Controller pattern. The first of these is the one that is most widely cited as a problem with Model-View-Controller, but in my opinion the second is the more difficult case to deal with, in spite of the fact that it’s hardly an unusual scenario:

1. Elements of our screen display depend on complex business logic

The canonical example here is coloring the background of a field in varying colors depending on the output from some business rule.

For example suppose we are showing daily sales figures for a business. We might want to color the background of a sales figure green if that figure is more than 10% above the average daily sales figure for the quarter, and color it red if it’s more than 15% below the average. Otherwise we leave the background white.

Model-View-Controller struggles with this scenario. Clearly it involves calculations involving business logic (averaging the sales figures for the quarter). In the Model-View-Controller pattern the business logic should go in the Model class. However, the only place we can sensibly put the coloring logic is in the View when it refreshes itself. We’ll come back to this below.

Note that we want to be able to enter the daily sales figure and have the background color change appropriately depending on the new value.

2. Elements of our screen display depend on what the user has selected in other screen components in a complex way

This could be as simple as a Save button being enabled only if the user has actually changed something on the screen (and being disabled again if the user changes the screen back to its original values).

Again the only place we can logically put this sort of logic in the Model-View-Controller pattern is in the View when it refreshes itself.

Whilst these problems are slightly different they can both be thought of as complex view logic surrounding the state of the user interface.

Why is Putting View Logic in the View a Problem?

In both of the examples above there probably isn’t all that much code relating to our view logic, and maybe putting it in the View in a Model-View-Controller pattern will be fine. However, with complicated screens this ‘view logic’ can run to many hundreds of lines of code. We don’t really want this code in our View, which we want to just be simple screen drawing code. Part of the idea of splitting out the View, after all, is that it becomes so simple we can easily replace it if we want to change our screen technology.

Another problem with having this logic in the View is that the event model may get quite complex. In my example it’s possible that a change in a sales figure that we’re not actually displaying could affect the background color of the textbox. Remember that we are comparing the textbox contents to the average daily sales. If the average daily sales change sufficiently we may need to raise an event to force a color change.

There’s another reason why developers prefer to get this ‘view logic’ out of the actual View class. It can be hard to automatically unit test a View class. Screen widgets often don’t lend themselves to unit testing. If the view logic is in another class it may be easier to unit test it.

Aside on Unit Testing in User Interfaces

I think the difficulties of unit testing user interfaces in Microsoft world are hugely exaggerated. Most Microsoft controls will let you do programmatically almost anything you can do with a mouse and keyboard. So, for example, we have a PerformClick method on a button, and settable SelectedIndex and SelectedItem properties on a ListBox. We can instantiate our screen in the test and interact with it programmatically in the same way we would if we were clicking on things. We have extensive unit tests that work this way in our current project.

It’s true that interactions between controls can be difficult to test (e.g. drag-drop operations). Also third-party (non-Microsoft) controls often don’t expose mouse and keyboard actions in the same way. However, in general you can usually unit test a user interface fairly extensively without recourse to restructuring your code as outlined in this article.

The Presenter in Model-View-Presenter

The first thing to understand about Model-View-Presenter is that it is very similar to Model-View-Controller, only with the Controller replaced with a Presenter (predictably).

The idea of the Presenter is that it can update the View directly. This isn’t permitted for a Controller in Model-View-Controller. This means we can put our complex ‘view logic’ described above into the Presenter and take it out of the View. Clearly we couldn’t do this with the Controller in Model-View-Controller since it had no easy way of updating the View with the results of the view logic: the View updated itself from the Model and the Controller was not involved.

Note that the Presenter, as with the Controller in Model-View-Controller, handles user events raised from the View as well. This means the View only contains screen drawing logic, which is what we want.

So a Presenter is able to ‘present’ data: it can directly update the View. On the other hand a Controller only controls: it takes user input and updates the Model as appropriate. Note that the Presenter is doing some controlling as well since it handles user events.

Diagram of Model-View-Presenter

Diagrammatically this looks as below:

As you can see, we again have three classes that interact. As with Model-View-Controller the Model class contains the data to be displayed, and the View class contains the code that actually draws the screen. We have already discussed the Presenter.

As with Model-View-Controller we can have multiple Presenter/View pairs of classes interacting with the same Model (with a change entered on one screen updating other screens showing the same data).

Class Interaction (active Model-View-Presenter with an active View)

When a user interacts with the View an event will be raised. This will be passed immediately to the Presenter (A). The Presenter will update the Model as appropriate (B): it may go back to the View to get the data it needs (F). The Model may at this stage raise an event that gets sunk in the View (C), leading to the View updating itself from the Model (D).

So far everything is the same as in active Model-View-Controller (except with the Controller replaced with the Presenter).

The difference is that when the Model is updated by the Presenter it may raise an event that also gets sunk back in the Presenter itself (E). The Presenter may then apply the complex view logic to work out what needs to be displayed before updating the View (F).

So in this version of Model-View-Presenter the View can update itself directly from the Model in simple cases where there is no view logic. When some view logic is needed the Presenter intervenes. It handles that logic and updates the View directly.

Interface on the View (F)

Another point to note here is that the Presenter accesses and updates the View through a clearly-defined interface on the View (F in the diagram). This has two effects. Firstly we can replace the View more easily with another screen technology since we know exactly what methods need to be exposed (those in the interface). Secondly this makes automated unit testing simpler. We can test the Presenter without needing screen elements directly by mocking the interface on the View in another class.

Conclusion

This article has described a basic Model-View-Presenter pattern and contrasted it with Model-View-Controller. It has examined why we need a different pattern to Model-View-Controller.

Part 24 of this series of articles will examine some variations on the Model-View-Presenter pattern described here, including the one in the Microsoft documentation for the SCSF. It will also discuss some of Martin Fowler’s user interface patterns that are relevant. References to articles for part 23 and part 24 will be given at the end of part 24.

An Apology, and Topics Still To Be Covered

Let me start by apologizing to all the CAB/SCSF fans (?) out there who have been asking me to continue the series of posts. I know it’s been a while since I wrote about the CAB/SCSF (I got diverted by FpML as you can see). However the series of articles is not yet finished and I will be sporadically posting on the topics many of you have been asking about. If there’s interest I may look at how to use some of the other application blocks with the CAB as well.

If there are specific things you would like to see covered please leave a comment.

Having said that, our CAB project is live and working well, and we are moving onto other issues, so my enthusiasm for spending my Saturday mornings writing about CAB/SCSF has waned somewhat.

Introduction

Part 21 of this series of articles briefly discussed foundational modules and the way constants are handled in an SCSF project.

Part 23 of this series of articles will examine another Smart Client Software Factory Guidance Automation pattern, the Model-View-Presenter.

By way of preparation for part 23, this article discusses the problems with putting code directly behind screens in smart client applications, and a traditional solution to this, which is Model-View-Controller.

The Basic Problem

When writing user interface code it’s quite easy to put too much logic in the class that draws a form or user control.

In badly-designed .Net applications, for example, it’s not uncommon to see classes behind user controls of several thousand lines of code (excluding the automatically generated code). We may have code that handles events, updates the data on the screen, caches and refreshes data, updates the state of user interface controls based on the data or user input, colors parts of the screen based on the data, binds data to controls in complex ways and so on.

With all this code in one class it can be difficult to work out what is going on. The code becomes hard to maintain.

Clearly if we have a lot of code doing different things in a class we are violating the single responsibility principle. We should be looking to refactor in such a way that we have a number of classes, each with a clear role and tidy interfaces into the other classes.

The difficulty with this is that it isn’t necessarily easy to see how to break up this sort of code in a logical way. There are a number of user interface patterns that address this. The granddaddy of them all is Model-View-Controller (MVC), although as we shall see this is not a pattern you are likely to see in a .Net application, at least in its original pure form.

Where to Cache the Data

It’s arguable that the main problem Model-View-Controller solves is that of data being cached directly behind a screen and not elsewhere in the application. Again this is a common problem in poorly written smart client applications.

Suppose we have a screen that displays data that has been retrieved into a series of textboxes directly from a middle-tier service. This data is loaded into the textboxes the first time it is displayed, retained in the textboxes but not actually stored in any variables anywhere. There may be a ‘refresh’ button that lets us reload the data from the service. However, the values in the textboxes will not automatically update if there’s a change server-side.

Suppose we now want to add another screen that uses that data in some calculations. Where does the second screen get the data from? If it goes back to middle-tier service the data may be out of sync with the data displayed in the screen. Should it go to the screen itself?

Model-View-Controller (MVC)

The traditional solution to this problem is to use the Model-View-Controller pattern (MVC).

MVC dictates that we have three classes for user interface display:

1. A Model class contains the data to be displayed. This can be a simple data cache, although it may be a full domain model (classes containing data plus associated business functionality).
2. A View class that contains the screen code. This would be a user control or form in .Net.
3. A Controller class that provides the glue between the Model and the View. This class is a little more difficult to understand than the other two. The idea is that the Controller handles all user input, which means events raised in response to user actions (e.g. clicking a button, changing a value in a textbox etc.). It then updates the Model as necessary.

Note that the Controller does not update the View. It updates the Model. If necessary the Model will then raise an event saying that it has changed. The View will subscribe to this event and redraw itself, getting the new data directly from the Model. Note that this is the Observer design pattern: the View(s) observe the Model.

In its purest form the View class should ONLY contain code that draws to the screen: it shouldn’t contain any event handling code for user events, all of which should be in the Controller. This isn’t actually possible with a .Net user control of course, where your event handlers have to be in the code behind the user control (the View). We can achieve the same effect by immediately calling the Controller from the View in the event handler. This means the View will have to have a reference to the Controller, which isn’t the case in the ‘pure’ MVC pattern (see below).

Class Interaction in Model-View-Controller

These classes should have references to each other as shown in the diagram below:

The solid arrows above represent references between classes through which direct method calls can be made.

The View class will have a reference to the Model to allow it to directly request the data it needs to display (A).

The Controller will have a reference to the Model because it will need to manipulate it in response to user actions (B). The Controller also has a reference to the View because it may need to retrieve values that have been changed in order to manipulate the Model in an appropriate way (C).

Note however that the Controller will not update the View directly. The View itself will go to the Model to actually get the data.

The dotted lines above represent an indirect relationship where events can be raised from one class into the other. So the Model may raise events when its data changes, which the View will sink and update any display depending on that data (D).

Note that the Model has no direct reference to the other two classes: it is independent of any Views or Controllers.

Use Case Examples

It can be difficult to understand exactly how this fits together when we see it for the first time. In particular what the Controller does can be confusing.

To clarify this here is a use case example:

• A user interacts with a screen displaying data (which is the View). Suppose that they change some base data and hit an Update button. Further suppose that they expect some derived data on the screen to change as a result of this action.
• The click event for the Update button gets raised in the Controller. A parameter to the event may be the data that needs to be saved (otherwise the Controller can go back to the View to get it). The Controller takes the changed data and updates the Model for the changes. This will include updating any derived data.
• The Model raises an event that it has changed.
• The View will sink the event and redraw itself based on the new data. This means that the correct derived data will now be displayed.
• The system waits for further user input when the cycle above will be repeated.

Solving the Data Caching Problem

MVC gives a solution to the data cache problem outlined above. We have separated the data for our screen into a Model class. Any other screen that needs to display the same data can access the same Model class (using its own Controller). The textboxes on the screens are effectively just views of this data whenever they are displayed.

As a result if the data changes it should only need to be changed in the one place (the Model) for the individual screens to be able to use it. What’s more, because the Model raises an event when the data changes, ALL we need do is change the data in the Model and all the screens will automatically update. If we change a value in a textbox on one screen it should update on any other screens via the process described in ‘Use Case Examples’ above.

Note that this means that one Model can be associated with multiple Views and Controllers. However, it is usual to have a one-to-one mapping between Views and Controllers: each View will have its own unique Controller class.

‘Pure’ Model-View-Controller

The Model-View-Controller pattern described in this article is one that could be used with modern programming languages such as .Net. The description here is what is usually meant by ‘MVC’ these days. However, MVC as described here differs slightly from the original pure MVC design. This article has already mentioned the fact that the Controller should directly handle all events raised by the user from the user interface, something that isn’t possible in .Net. There’s one other fairly major difference with the pure MVC pattern.

MVC originated with early Smalltalk which was a very different language from modern user interface languages like .Net or Java. For a detailed look at the history of MVC (and of MVP) see Martin Fowler’s article ‘GUI Architectures’.

In the original Smalltalk design every single control (textbox, button, etc.) would have its OWN View and Controller class, and the screen they were on would have a top-level View and Controller that would handle putting them all together. This was because Smalltalk didn’t have draggable user interface controls in the way we do today, so writing a user interface was a somewhat different proposition.

Clearly we could do this in a modern programming language such as .Net, but it would arguably make our code less clear rather than clearer.

Active and Passive Model-View-Controller

MVC as described here is ‘active’ MVC. This means that, as we have seen, if the Model changes all Views will be updated automatically via the eventing mechanism.

It is also possible to set up ‘passive’ MVC. This is a slightly simpler pattern where the Model does not raise an event when it changes, and consequently the View cannot update itself ‘automatically’. Instead the View is updated when the user next requests it (by pressing a ‘Refresh’ button for instance). At this time the View will go to the Model and get the new data.

Advantages of Model-View-Controller

MVC obviously has the advantage that for complex screen logic we get clearer code, which should be easier to maintain. In theory this pattern also makes it easier for us to replace the user interface itself, since only screen logic is in the screen.

MVC also provides an easy way of allowing multiple views of the same data to always be synchronized (via the event mechanism).

Disadvantages of Model-View-Controller

Of course, there’s one obvious argument against using MVC for every single screen in a system: it’s a fairly complex pattern, and for very simple screens may simply mean we create three classes where we only need one. Also you clearly have to learn the pattern to be able to use it effectively, which is an overhead.

MVC also suffers from the same problem that all eventing mechanisms have: it can be hard to debug. When the Model fires an event saying it has changed it may not be immediately obvious where this event is being sunk, and finding out in order to debug the code may be tricky.

However, the biggest problem with MVC is that it doesn’t actually solve all of the issues involved in the original problem described in this article. There are multiple reasons why we might have too much code behind our screens, and for some of these it’s not clear how MVC helps us. For this we may need a slightly different pattern, which might be the Model-View-Presenter pattern the SCSF gives us.

This will be discussed at greater length in part 23 of this series of articles.

Conclusion

Model-View-Controller is a pattern that can be used to structure the code in a user interface in a logical way, and prevent too much code being in the screen class itself. In particular it splits the data for a screen into a separate class.

However, it doesn’t solve all our user interface coding problems as we shall see in the part 23 of this series of articles. For this reason it’s not all that common in modern .Net applications.

References

Martin Fowler on MVC and MVP
http://www.martinfowler.com/eaaDev/uiArchs.html

MVC was originally designed for Smalltalk
http://st-www.cs.uiuc.edu/users/smarch/st-docs/mvc.html

Microsoft on MVC
http://msdn2.microsoft.com/en-us/library/ms978748.aspx

Part 1 Introduction

An overview of how we can use Visual Studio to examine the FpML XSDs. Shows how to create a Visual Studio project containing the FpML schemas, and how to use that to navigate through them. Also shows how to validate the XML examples that are provided in the FpML download, both using Visual Studio and in C# code.

Part 2 How FpML Validates A Basic Trade Document

Looks at the structure of an FpML trade document in some detail. Explains how the FpML schemas fit together to validate such a document, and examines the use of base and extension types, and of substitution groups, in the XSDs.

Part 3 Generating .Net Classes From The FpML XSD Schema

Shows how to generate .Net classes in C# from the XML schema documents using Xsd.exe.  Explains how to load data into these classes from an FpML document using C# code, and to save the document back out again from the classes.

Part 4 Problems With Using Xsd.exe To Generate .Net Classes From The FpML XSD Schema

Goes through some of the problems with the C# code generated in part 3, and discusses how to fix them.

Introduction

Part 3 of this series of articles showed how we can generate .NET classes from the FpML XSD schema using xsd.exe. It showed how we can then use standard .NET serialization syntax to populate the classes from FpML documents, and vice versa.

However, as mentioned in part 3, xsd.exe generates buggy code when used with the FpML XSDs. This article will go through some of the problems with this code and describe how to fix them.

Corrected .NET Classes

Corrected generated classes, which are the end result of the work in this article, are available. This code has been corrected such that it appears to work in most circumstances. However we cannot be certain that it is free of all bugs.

The corrected code is based on FpML 4.2. The main aim of this article is to give you a starting point if you are trying to generate .NET code from other versions of the specification.

Please note also that this article was written using the xsd.exe supplied with Visual Studio 2005 Service Pack 1. Different versions of Visual Studio, or Visual Studio 2005 without the service pack applied, may give different results. See the discussion in the Comments for this article for more details.

Generating the Code

Part 3 of this series of articles described how to use xsd.exe to generate C# code from the FpML schemas. This gave us a file called fpml-main-4-2_xmldsig-core-schema.cs, which contains a Document class which should be the root class for our serialization. Unfortunately if we attempt to create an XmlSerializer object using this code we get exceptions.

Problem 1: Substitution Groups and Extension

The most fundamental problem with our generated code is that xsd.exe has got confused about the substitution groups and associated extension that were discussed in some detail in part 2 of this series of articles.

In particular it has not decorated the Product property of our Trade class correctly to allow it to deal with all the possible products correctly.

In part 2 we saw that the product element in the FpML is replaced with various individual product types using the substitutionGroup syntax. The product element is a sub-element of the trade element in the XML. As a result in our C# code we have a Trade class which contains a data member of type Product and a public property that gets and sets this. Excerpts from our generated code are as below:

[System.CodeDom.Compiler.GeneratedCodeAttribute("xsd", "2.0.50727.42")]
[System.SerializableAttribute()]
[System.Diagnostics.DebuggerStepThroughAttribute()]
[System.ComponentModel.DesignerCategoryAttribute("code")]
[System.Xml.Serialization.XmlTypeAttribute(Namespace="http://www.fpml.org/2005/FpML-4-2")]
public partial class Trade {
 
    private Product productField;
 
    public Product product {
        get {
            return this.productField;
        }
        set {
            this.productField = value;
        }
    }

The problem with this code is that, as we saw in part 2, we need to be able to put a Swap object (for example) in to our Product data member. We have a Swap class in our code, and this inherits Product, as we’d expect. So we can store a Swap object in our Product data member.

However, .NET doesn’t know how to serialize or deserialize a swap element in the XML into our product property without being told. In particular, if the deserializer finds an element called ‘swap’ where it’s expecting ‘product’ it doesn’t know that it should deserialize into a Swap object. As we saw in part 2, in ird_ex01_vanilla_swap.xml there is a ‘swap’ element where you might expect a ‘product’ element.

This is very easily fixed in this case. We simply decorate the Product property with an XmlElementAttribute that tells the serializer what to do:

    [System.Xml.Serialization.XmlElementAttribute("swap", typeof(Swap))]
    public Product product {
        get {
            return this.productField;
        }
        set {
            this.productField = value;
        }
    }

This does solve the problem for swap. However, there are multiple other product types that need the XmlElementAttribute added to Product to get the serialization to work (there are over twenty in fact). Also it turns out that this problem isn’t limited to Product. There are other elements that use the substitution group and extension property in this way and have the same problem

At first glance it appears there is no easy solution to this: we are going to have to go through all the possible places where there might be errors and correct the code by hand. However, there’s a much easier solution.

Problem 1 Solution

For simple examples of this problem xsd.exe will correctly generate the required XmlElementAttribute. It’s not immediately obvious why it fails to do so with the full FpML schemas.

It turns out that the reason xsd.exe gets this wrong is because the FpML schemas are spread across multiple files. If we create one big xsd file containing all of the FpML schema files and then run xsd.exe on this the problem goes away. I’ll leave you to draw your own conclusions about the quality of the xsd.exe code.

So to fix the problem we can cut and paste all of the FpML xsd files into one file, removing the include statements that become redundant. An example of this is available. We then use xsd.exe as described in part 3 to create our C# classes.

Problem 2: RoutingIds

If we fix problem 1 as above, we still get an error when we try to create our XmlSerializer object. The error message says ‘Connot convert type ‘RoutingId[]’ to ‘RoutingId’’.

This exception arises because xsd.exe has got an XmlArrayItemAttribute wrong in class RoutingIdsAndExplicitDetails. The generated code for the routingIds property in this class is as below:

    [System.Xml.Serialization.XmlArrayItemAttribute("routingId", typeof(RoutingId), IsNullable=false)]
    public RoutingId[][] routingIds {
        get {
            return this.routingIdsField;
        }
        set {
            this.routingIdsField = value;
        }
    }

The XmlArrayItemAttribute says that the property relates to an array of type RoutingId. However, the property (correctly) is of type RoutingId[][] which is an array of arrays of type RoutingId. So the XmlArrayItemAttribute should be changed as below:

    [System.Xml.Serialization.XmlArrayItemAttribute("routingId", typeof(RoutingId[]), IsNullable=false)]
    public RoutingId[][] routingIds {
        get {
            return this.routingIdsField;
        }
        set {
            this.routingIdsField = value;
        }
    }

Testing the Generated Classes

The two fixes above appear to make the generated classes work correctly. With these changes we can deserialize our ird_ex01_vanilla_swap.xml FpML document into the classes. We can then serialize it back into XML, and we end up with the same document we started. We saw this in one of our code examples from part 3. It’s not easy to test this code is working in all cases however. One approach is to take all the sample FpML files provided with the FpML download and attempt to deserialize them and reserialize them. The code is working if the final document is the same as the original one.

Testing Program

A testing program that does this is available. This contains the code we have seen before (in part 3) for serialization and deserialization.

It also contains a basic class for comparing the original and final FpML documents and outputting any differences. It does this simply by iterating through the lines in the two files and comparing them. This may not be the best way to do this as it is quite difficult with XML.

It is difficult because there can be valid differences between the files that are hard to deal with. For example we have a ‘difference’ where the original line is:

<hourMinuteTime>09:00:00</hourMinuteTime>

After deserialization and reserialization this becomes:

<hourMinuteTime>09:00:00.0000000+00:00</hourMinuteTime>

These are clearly the same thing but our file comparer has to be able to deal with it. It does so in a very basic way by hard-coding such differences to be ignored in method ‘CompareLines’.

Extent of Testing of Generated Code

Because of the difficulties described above the testing program has only been used to test that the generated code works with the interest rate derivatives and credit derivatives sample files.

Usefulness of Generated Classes

In the last two articles we have demonstrated that we can generate C# classes based on the FpML XSD specification, and with a little work can deserialize FpML documents into this object model, manipulate the objects, and serialize back into FpML.

However, my personal opinion is that we need to think carefully as to whether we want to use these classes. FpML has a very hierarchical structure, and as a result in the generated code we have very many classes interacting to represent even a simple trade. Our object model is not very easy to understand or use as a result.

For example, suppose we want to change the notional on the fixed leg of our interest rate swap (ird_ex01_vanilla_swap.xml) once we have it in the object model. Starting with the top-level Document object that we have deserialized, the syntax is as below:

        private void ChangeNotional(Document document)
        {
            DataDocument dataDocument = (DataDocument)document;
            Trade trade = (Trade)dataDocument.Items[0];
            Swap swap = (Swap)trade.Item;
            InterestRateStream interestRateStream0 = swap.swapStream[0];
            InterestRateStream interestRateStream1 = swap.swapStream[1];
            Calculation calculation1 = (Calculation)interestRateStream1.calculationPeriodAmount.Item;
            Notional notional = (Notional)calculation1.Item;
            notional.notionalStepSchedule.initialValue = 1000000;
        }

In fact, I don’t think this routine is complex enough, since it should really check which of interestRateStream0 and interestRateStream1 is the fixed leg.

A code example incorporating this code is available.

It’s hard to argue that this code is straightforward: for instance we have a number of ‘Item’ properties referenced that can be of various types. We have to know which type we want. In addition we have the issue that we are not entirely sure that the code generated by xsd.exe is free of bugs, even after the work we have done to patch it up.

As a result in a current project I am working on we have decided not to use the classes generated by xsd.exe, but instead to deserialize into flatter structures of our own design.

Conclusion

This article has shown that it is possible to fix the code generated by xsd.exe from the FpML schemas such that we can deserialize/serialize FpML documents into/out of the object model. We have also shown that it is difficult to test that this will work correctly in all cases, and that the resulting object model is not all that easy to use.

Licensing of FpML Specifications

The FpML Specifications of this document are subject to the FpML Public License (the “License”); you may not use the FpML Specifications except in compliance with the License. You may obtain a copy of the License at http://www.FpML.org.
The FpML Specifications distributed under the License are distributed on an “AS IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Licensor of the FpML Specifications is the International Swaps and Derivatives Association, Inc. All Rights Reserved.

http://www.fpml.org/documents/license.html

Introduction

Part one of this series of articles looked at how we can use Visual Studio to examine the FpML XML schema documents (XSDs), and the associated example XML instance documents.

Part two of the series looked in some detail at the structure of an FpML trade XML document, and showed how to investigate its validation against the schemas using Visual Studio.

This article will show how to generate .NET classes in C# from the XML schema documents. These classes can in theory be used to load FpML documents into objects. These objects can then be manipulated by the code and saved out as FpML. However, there are some problems with the Microsoft tools for doing this, as we shall see.

Motivation

FpML is a powerful way of representing financial products in a standard way. It can be used to pass trade data between financial institutions in an XML format that both parties can understand. It can also be used to pass trade data between computer systems within a financial institution. If all systems know about FpML then we have a standard platform-independent human-readable representation of our data that everyone can use.

Clearly there are some disadvantages to using FpML in this way (it’s very verbose, and we will probably need to modify it for our own needs anyway, in which case it stops being standard). However there’s a prevailing view that FpML is a good place to start when defining what trade data and messages we will pass around in a service-oriented architecture in a bank.

However if we want to use trade data passed to us as FpML we need to get it into a format we can program against. Obviously if we are programming in .NET languages we want to have objects, or even DataSets. Furthermore we’d like to be able to modify those objects or DataSets and then turn them back into valid FpML documents.

The XML Schema Definition Tool (xsd.exe)

Microsoft have provided an ‘XML Schema Definition Tool’ called xsd.exe that purports to allow us to do this. It claims to be able to turn XSDs into classes. These classes can then be used to automatically load associated XML instance documents into objects, and back into XML again after manipulation. xsd.exe is also capable of creating DataSets from XSD files.

Obviously loading XML instance documents into objects is XML deserialization, and turning them back into XML is serialization. Once we have the classes we can use .NET’s standard serialization mechanisms for this.

As we shall see, this doesn’t work particularly well with the FpML schemas.

Generating C# Classes from FpML Schemas

To use xsd.exe to generate C# classes is relatively straightforward:

1. 1. Start a Visual Studio command prompt (this is under ‘Microsoft Visual Studio/Visual Studio Tools’ on your start menu).
2. Navigate to a folder where the FpML XSD files are. If you created the console application used in parts 1 and 2 of this series of articles navigate to the project folder (which has the XSDs in it).
3. Run the command below:
   xsd /c fpml-main-4-2.xsd xmldsig-core-schema.xsd
   This generates a file called fpml-main-4-2_xmldsig-core-schema.cs which contains the classes we need.

Note that the /c parameter asks xsd to generate classes. There is also a /d parameter that asks xsd to generate DataSets. We will discuss this option later.

Note also that we only need reference the root schema file (fpml-main-4-2.xsd) for this to work: the other schema files are referenced from this file (with include statements) and xsd can work this out. However xsd can’t work out what to do with the xmldsig-core-schema.xsd file unless we tell it to process it. This is because only the namespace is referenced in the schema files, not the file itself.

Using the Generated C# Classes

If we look at the fpml-main-4-2_xmldsig-core-schema.cs file we see that we have nearly 37,000 lines of code, including over 650 classes. As you’d expect these classes use .NET’s XML serialization attributes throughout, so we can serialize into and deserialize from XML correctly. The root class is Document.

To use these classes we need to create an XmlSerializer object based on the root Document in code. This is standard .NET serialization code:

        XmlSerializer xmlSerializer = new XmlSerializer(typeof(Document));

Then in theory we should be able to deserialize any FpML document into these classes using the XmlSerializer. The syntax we’d use for this is as below:

        internal Document DeserializeXMLToDocument(FileInfo inputXMLFile)
        {
            using (FileStream fileStream = File.OpenRead(inputXMLFile.FullName))
            {
                return (Document)xmlSerializer.Deserialize(fileStream);
            }
        }

Once we’ve deserialized into objects based on our classes, we should be able to serialize those back into XML. Clearly the final XML should be the same as the initial XML. The syntax for the serialization is as below:

        internal void SerializeDocumentToXML(Document document, FileInfo outputXMLFile)
        {
            using (FileStream outFileStream = new FileStream(outputXMLFile.FullName, FileMode.Create))
            {
                xmlSerializer.Serialize(outFileStream, document);
            }
        }

This is all standard .NET XML serialization code.

First Attempt to Use the Generated Classes

We can write a basic harness that uses our generated classes and the code above to attempt to deserialize and serialize FpML files.

A version of this is available. It tries to deserialize the ird_ex01_vanilla_swap.xml that was examined in part 2 of this series of articles.

Unfortunately the classes generated by xsd.exe have a number of problems, and unless we correct these the basic harness will not work. In fact we can’t even create the XmlSerializer object successfully with the generated code.

Part four of this series of articles will examine the various problems with the code that xsd.exe has generated, and will discuss how to correct them.

Corrected Generated Classes and a Working Harness

Corrected generated classes are available. As will be discussed in part four this code has been corrected such that it appears to work in most circumstances. However we cannot be certain that it is free of all bugs.

A version of the harness that uses the corrected code is also available. As you can see if you run it, this does correctly deserialize and then reserialize ird_ex01_vanilla_swap.xml.

Conclusion

This article has shown that in theory we can generate classes from the FpML XSDs using xsd.exe. We should then be able to deserialize FpML documents into these classes, manipulate the resulting objects, and then reserialize back into valid FpML documents. However, xsd.exe has some problems that prevent this from working correctly.

Part four of this series of articles will look in more detail at the problems in the generated code, and how to fix them.

Licensing of FpML Specifications

The FpML Specifications of this document are subject to the FpML Public License (the “License”); you may not use the FpML Specifications except in compliance with the License. You may obtain a copy of the License at http://www.FpML.org.
The FpML Specifications distributed under the License are distributed on an “AS IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Licensor of the FpML Specifications is the International Swaps and Derivatives Association, Inc. All Rights Reserved.

http://www.fpml.org/documents/license.html

Introduction

Part 1 of this series of articles gave a general introduction to using Microsoft .NET tools to investigate FpML XSD schemas.

This article will focus more closely on the FpML itself, by looking at the structure of an FpML trade XML document in some detail. It will explain how the FpML schemas fit together to validate such a document. In particular it will examine the use of base and extension types, and of substitution groups, in the XSDs.

As mentioned in part 1, FpML is complex and there’s little documentation. This article will attempt to redress this by explaining how it works assuming only that you know the basics of how an XSD works.

These articles assume you understand the basics of XML Schema Definition language. If you don’t there are a number of good tutorials available on the internet. For example there’s quite a good one at http://www.w3.org/TR/xmlschema-0/. These articles will reference the tutorial for the less obvious XSD structures.

The fpml-main Schema

In part one of this series of articles we showed that the file ird_ex01_vanilla_swap.xml is a valid document in accordance with the FpML schemas. ird_ex01_vanilla_swap.xml is an example file provided with the FpML download that represents a simple interest rate swap. However, at first glance it’s not entirely clear how the large number of XSD files that define the FpML schema fit together to validate this XML document.

The first thing to notice is that the XML document references the main root schema fpml-main-4-2.xsd in namespace http://www.fpml.org/2005/FpML-4-2. FpML puts all its definitions in one namespace, which for the version we are using is http://www.fpml.org/2005/FpML-4-2.

If we look at file fpml-main-4-2.xsd and collapse it to an appropriate level we see something as below. I’ve moved the schema attributes onto multiple lines for clarity:

As we can see, this XSD defines a number of namespaces, sets our targetNamespace for the schema, and includes a number of other XSDs from the set of FpML XSDs. It defines one complex type, ValuationDocument. Remember that complex types only have to appear in the XML if they are referenced as the type of an element: ValuationDocument does not have to appear in any XML just by virtue of being in this document.

The schema finally defines the one mandatory top-level element in this document, which is an element called ‘FpML’ which is of type ‘Document’. If we expand the FpML element definition we find it just contains an annotation (comment). So in effect all this schema is saying is that our root element for an FpML document must be called ‘FpML’ and it must be a Document.

Schemas Needed to Validate an Interest Rate Swap

It’s also worth noting here that we don’t need all the XSDs that are imported here to validate the interest rate swap successfully. In fact we can comment them all out apart from fpml-ird-4-2.xsd, provided we add an import for fpml-doc-4-2.xsd (which is included in fpml-valuation-4-2.xsd). We need to comment out the ValuationDocument complex type as well if we do this.

Note you can use the usual comment out/uncomment buttons in Visual Studio to comment XML (and hence XSD) code.

So the ird_ex01_vanilla_swap.xml file will validate with fpml-main changed as below. This makes it clear that we are only using a subset of our XSD files to validate an interest swap, which is what you’d expect. Note that fpml-ird-4-2.xsd itself includes a number of other FpML schemas, so we are not JUST validating with the two included below:

Document Type

We can now navigate to the Document complex type, which is in file fpml-doc-4-2.xsd. Remember that to do this in Visual Studio all we need do is right-click “Document” and select “Go to definition” (or hit F12). We see that Document is defined as ‘abstract’. This is equivalent to a class being abstract in C#. It means we can’t use Document directly as the type of an element, but have to derive from it first. Document also contains an attributeGroup that references StandardAttributes.atts. This has one mandatory attribute ‘version’ (which applies to the FpML element), and can have value “4-0”, “4-1”, or “4-2”.

So now we need to know what complex types derive from the Document type. The easiest way to find this out using Visual Studio is to search our project for “Document” (in quotes), since any extension has to use the extension syntax which looks like:

<xsd:extension base="Document">

If we do this we find there are two types that extend Document: “DataDocument” and “Message”. Obviously the ‘Message’ type of document is used for messaging. Here we are only looking at trade representations in XML, which use the DataDocument type of Document.

The XML Document

If we now look at our instance XML document we see that, as expected, it starts with an FpML tag, which has a version attribute. It then uses the xsi:type attribute to specify that we are using a DataDocument.

Most FpML trade documents will have the general structure below, as we shall see. That is, the root FpML element will contain a trade element and a number of party elements. The trade element will contain a tradeHeader element, and an element that represents a specific product, in this case swap. For other product types the swap element will be substituted directly with some other product element.

DataDocument

We saw above that our FpML element is of type DataDocument. The DataDocument definition is in fpml-doc-4-2.xsd, and a summarized version is below. If we look at the full version we can see there is a comment that says that the data document is intended to ‘contain sets of data without expressing any processing intention’:

As expected this extends Document. It adds a sequence, starting with a Validation.model group. The element in this group is optional, so it doesn’t don’t appear in our XML at all.

The next item in our schema is a choice between a sequence of trade and portfolio elements, or of an event element. Our XML uses the trade and portfolio choice. Note that both of these are optional (minOccurs = 0), and our XML has no portfolio element. We examine the Trade element in more detail below.

Finally in our sequence we can have multiple (or zero) elements called ‘party’. These are intended to identify any parties to the trade (see the comments in the full version of the XSD). They are of type Party: this has an ‘id’ attribute, a required ‘partyId’ element, and optional partyName and account elements. If you look again at our XML you can see that we have two ‘party’ elements defined, with just the id attribute and mandatory partyId provided.

Trade

So in an FpML document we have a root element called ‘FpML’ that has to be of type Document. Document is abstract, and one extension is DataDocument, which can contain an element called ‘trade’ of type Trade.

The XSD definition of the Trade complex type is below:

The first thing to notice is that everything is optional (minOccurs=0) apart from the tradeHeader element, and the referenced product element. These two elements are the only ones that appear in our sample XML (although indirectly in the case of product, as we shall see below).

TradeHeader

By now you’ve probably got the idea of how this works and how to use Visual Studio to navigate through the schema and find out what needs to be where in the XML. As a result we won’t go into how the tradeHeader element is constructed, which is straightforward. The comment on the TradeHeader complex type says ‘a type defining trade related information which is not product specific’, which is self-explanatory.

It’s interesting to note that the ONLY information relating to a trade that is not ‘product specific’ here is the trade date and at least one trade ID (along with whose ID it is). If you are constructing a base trade class for a hierarchy of trade types this is really the only data you can meaningfully put in it.

Product and Swap

The product element is a little more complex. If we look again at our sample XML we see that we have a ‘swap’ element in the XML where we expect the ‘product’ element to be.

If we go to the definition of the referenced product element we find that it is of complex type Product, is abstract, and is defined in fpml-shared-4-2.xsd.

However, in spite of the product element (and its associated type Product) being abstract the schemas are not using straightforward extension here. Hence there is no ‘xsi:type’ attribute in our XML instance document. Instead we are using substitution groups.

If we locate the definition of ‘swap’ in fpml-ird-4-2.xsd we see that it is an element of type Swap with substitutionGroup of product. This means it can be substituted directly for the product element in our final XML (as can any other element tagged in this way):

  <xsd:element name="swap" type="Swap" substitutionGroup="product">
    <xsd:annotation>
      <xsd:documentation xml:lang="en">A swap product definition.</xsd:documentation>
    </xsd:annotation>
  </xsd:element>

The substitution group syntax on its own means that element swap and type Swap need have no relation to type Product. Swap could be a completely new type with no reference to the base Product type. We can substitute whatever we like for the product element.

However, in the FpML schemas complex type Swap also extends type Product, which means this element has to take account of the definition of the Product complex type.

So, to summarize, we have a ’swap’ element in our XML document where there is a ‘product’ element in the XSD. We can put the swap element in there because of the substitution group syntax: we just substitute the swap element for the product element. However, the swap element is also of type Swap which extends type Product, so it must take account of the Product definition as well.

This is certainly difficult to understand.

Product itself is abstract, has an id attribute and contains a named group called ‘Product.model’. However, all of this is optional and does not consequently appear in our sample instance XML.

Difficulties with Substitution Groups for product in the FpML

As explained above, the use of both substitution groups and extension to replace product elements in the FpML schemas is confusing.

In my opinion even if we ignore the use of extension the use of substitution groups is confusing for developers. Most XSD constructs map to object oriented concepts. However, because we are using substitution groups here we are effectively saying that absolutely any type can be a member of our parent trade type at this point in the schema. It’s like including a generic object data member in a class that can be used to contain ANY other class. In OO terms we have no idea what interface this object will implement. It’s hard to represent this in UML as well: see http://www.xmlmodeling.com/documentation/specs/substitutionGroup. Finally, as we shall see in part 3, the Microsoft tool for creating classes from schemas (xsd.exe) struggles with the combination of extension and substitution groups used in the FpML schemas.

Swap

The Swap complex type is again fairly straightforward. Everything is optional except for at least one element called swapStream, of type InterestRateStream. Clearly these represent the swap legs for our interest rate swap, and consequently we have two of them in our sample instance XML. As mentioned above you’ve probably got the idea of how this all fits together by now, and how to investigate further, so we’ll leave the schemas at this point.

Conclusion

This article has attempted to show how validation using the FpML schemas works, and to give an idea of the structure of a trade XML document in FpML.

Part three of this series of articles will examine how we can generate .NET classes from these schemas using xsd.exe, and will look at some of the problems associated with doing this.

Licensing of FpML Specifications

The FpML Specifications of this document are subject to the FpML Public License (the “License”); you may not use the FpML Specifications except in compliance with the License. You may obtain a copy of the License at http://www.FpML.org.
The FpML Specifications distributed under the License are distributed on an “AS IS” basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Licensor of the FpML Specifications is the International Swaps and Derivatives Association, Inc. All Rights Reserved.

http://www.fpml.org/documents/license.html