Dag König

How to create one method of the web service

In my last article I tried to show how to find the different web services that an organization could expose to their customers, how to separate them and finally how to expose the operations (methods) inside one service. In this article will concentrate on only one operation, RenewDrivingLicense, and see how this should be defined with help of schemas (XSD).
The operation RenewDrivingLicense has two messages associated with it. It is one that contain the request to the operation and one that contain the response from the operation. (We could also have a third which is a special message that the operation will send if anything goes wrong.)
In my first article I showed an example of this service. In that example the request and the response was two documents, an application form and (hopefully) a driving license. This way to communicate with the service is called document literal and is the preferred approach when working with services. (A different method is to use rpc literal, which is more like method calls within a program where several parameters is used in the call.)

The first thing that I do with these documents is to name them. I use that by combining the name of the operation and, as the second part of the name, "request" or "response". This is not only a practical way to name things. This is done because we want to make the documents strict related to the operation. What do I mean by that?
We are still working on the contract of a service and its operations and messages. When we do that, we have to be as explicit as possible so that other could use it. (This is a long discussion that we could dig into deeper some other time.)

How to describe the documents?
The documents should of course be described as Xsd schemas. But it is not always easy to start writing them from scratch. We probably have to model them in some way. Currently I use two approaches to do this. We could use Uml to describe them as class diagrams or we could start writing examples of the documents in Xml. I prefer the first way when I do larger system. I think also that this is the preferred way when we start to have many schemas in a library. (This approach will I describe in the next article of this series.) The second way is still good to have when you start. It's also simple to have as a base for discussion.
Below is an example of these documents, the request and the response, as xml.

The xml has two other advantages:
1) Xsd Schemas can be generated from them.
2) They could later be used in tests as test data.

From Uml/Xml to Xsd Schema
The easiest way, as I said before, is to generate schemas from the xml examples. This could be done in Visual Studio. A different way is to use Xml Spy and start writing the schema.
This is really simple to do. The problem arise when we starts to do this on a larger scale. We will soon have the possibility to reuse parts and this is not easily done if we use this simple way to make schemas.

This will I talk about in my next article. To be continued...

 

A day of blog silence for the victims in the Asian quake disaster

What should I say a day like this? This week is a time of despair and agony for many of us. So far away but also so near that we could still feel the heart beat of them that no longer are with us.

It is also a week where the human heart turns away from itself and instead turns toward each other with help and love.
 

I will honor them with a day of silence and praying...

Geek Dinner in Stockholm

Are you interested to come? Go to this site and find out more.

http://www.dopplerradio.net/doppler/log.pma/ViewEntry?OpenPage&ID=39

Out for lunch

This month has been rather tough for me. I currently have three different assignments. So I have not had the time to write so much here on my blog. I'm also thinking about doing my blog bilingual again. It's not always easy to write in English and express your thoughts. Put I also like to train my English and to have readers from other countries.

I hope that I soon will have the possibility to have several rss feeds, one for each language.
 

Amazon is spamming me with packages

This Christmas has I decided to buy most of my presents on the Internet. I don't like fighting my way though shops in Stockholm. I really like books, so Amazon is a place that I often go to. This month has I ordered seven things, books and calendars. 

The last days they have spammed me with packages because of that. Each thing is coming in its own package. I five days have a received four packages. What does my letter carrier think of me?

From services in a organization to wsdl

This is part two in my article series about implementing services with “contract first”. Please read the first one for some background information.

Let me give an example. Banks have several different counters. (Or, it was so in the old days, before Internet) One counter is assigned for accounts tasks, other for loans and a third for information and other tasks. We could say that the bank has three different services that they expose to their customers.

This is the same for TSV. They have several services that they expose to their customers.

In our example they are:

• Driving License
• Car Registration
• Information

These services are also a good start to identify as different web services. (This is of course the public web services. TSV could (and probably should) also implement other web services that are used inside the organization.  

We now concentrate us on the Driving License Service. This service supports several processes.
The four processes that they have are the following ones:

• Apply for Driving License
• Renew Driving License
• Get information about Driving Licenses
• Terminate a Driving License

A different way to describe this is to draw a use case diagram. In this diagram we also describe the actors that use the processes.
We have two actors:

• Ordinary User - Can only use services that are bound to their own license.
• Privilege User (Police, Administrative personnel, and such) - Can use services that has the user rights to all licenses.

Now we have enough information to make our first wsdl file. (We haven't yet described the information that be passed. This is the topic for the next article in this series.)

I divide the TSV web services in the following way. Each service and role will become its own wsdl file. I call each of them its on service interface (SI).
So in our example we will have the following wsdl's:

• DrivingLicenseUserSI.Wsdl
• DrivingLicensePrivUserSI.Wsdl
• CarRegistrationUserSI.Wsdl
• CarRegistrationPrivUserSI.Wsdl
• InformationUserSI.Wsdl
• InformationPrivUserSI.Wsdl

(The actors for the services Car Registration and Information could be different. I have included them to make the example more complete.)

The DrivingLicenseUserSI defines ApplyForDrivingLicense and RenewDrivingLicense processes and DrivingLicensePrivUserSI defines GetInformationAboutDrivingLicenses and TerminateDrivingLicense.

The reason to have a wsdl for each actor is that it is easier to implement different contract and polices in this way. For example: The processes that only Privilege User could access needs to implement more security. (It could be encryption, authorization.)

In the next article will I drill down in the DrivingLicenseUserSI and show how to describe the information that will be passed to and from the processes.

Do you want to work with me?

My company, Know IT, is hiring again. We have a couple of places left in my team. Are you interested? Read more here.

Architect Forum 2004

Sitting right now at whole day presentation about SOA with the Swedish regional directors, Sten and Per Sundblad. We are about 160 attendants. Sitting in a cinema. Nice, but no pop-corn.

SNIPPETS
(1) Visual Studio 2005 will probably be release in Q3, not earlier. I am not surprised. Some parts of the product will probably be released a bit later as separate modules.
(2) Visual Studio 2005 will be released in several different configurations. The whole product will probably be just a bit more expansive then the other ones, which means that most people will by the whole suite.
(3) Visual Studio Express Editions - So easy that your mother could use it. (Joke)

OTHER INFORMATION
Just one crash when showing Team Systems. It's nice but not finished at all. I wonder if this could be one of the modules that will be released a bit later than the main product. Later they said that the Team Service will be released 90 days after the initial Visual Studio release. I will probably use it often when the product is released. I wonder how fast the synchronization will be in large solutions. I hope that this feature could be turned off.

MICHELE FREED
Platforms Technical Assistant
She talked about the platform (windows operating system) project lifecycle. How they eat their own dog food. Interesting presentation.
After this she focused on the Team System. It looks like Microsoft really prioritizes this part of Visual Studio 2005. It will probably be the selling "gem" in this version of Visual Studio.

THE DIFFERENCE BETWEEN FUNCTIONAL ORGANIZATION AND ORGANIZATION HIERARCHY
The functions still exist but the organization will change. The organization is not as stable as the functional. This means that we should map our services against the functional organization, not the organization hierarchy. This will also compensate for the application and service spaghetti that otherwise could be a problem. An interesting model to describe the functions is Capability mapping. I hope that I some day could write more about this model and how to use it.

SUMMARY
It was a good day, well spend.

A Brief History of Video Game Humor

This is a really good article from GameSpot about humor in games. I think that the games that I remember are those that contained much humor.

Almost every adventure game that Lucas Art released was truly good in that aspect. But where are the new ones? The last, that I remember, was "Escape from Monkey Island", which was released in 2001.

A Brief History of Video Game Humor

How Xsd and Wsdl could be used when creating document-oriented web services

This is an example, or rather a small story, that tries to show how schemas are used (or could be used) when a web service method is called. The example shows a document-oriented solution to this problem. That means that we only use one parameter as the input to the method and only one parameter as output from the method. Each of these parameters is an xml document that contains several elements.

THE STORY - CARL SHOULD RENEW HIS DRIVING LICENSE
Carl's, the little yellow guy, has to renew his rather old driving license with a new one.

In Sweden this is done (or was until 1993) at a central Motor Vehicles office called TSV. This office has several different services, where Driving License is just one of them. This service is represented by the little green guy. We could call her Greta.

The first thing that Carl needs to do is to get an application form for renewing his driving license. He gets that from TSV.

The next thing that Carl does is to fill out the form and return it to Greta. It is now that the process, for Greta anyway, starts.

Greta takes the supplied form and check first if it is correctly entered. That's no problem because Carl has very carefully filled in the form. The next thing that Greta does is to start the process to renew his license. This is not a simple task. She has to look in three registers. You located in the basement and open only on Thursdays between nine and eleven.

Fourteen days later the paperwork for Greta is finished and everything has gone very well. Now is the time for Greta to return the new Driving License to Carl. She takes an empty driving license template and fills it out.

The last thing that she does is to send it to Carl.

This rather silly example tries to show how a web service method, here called RenewDrivingLicense is processed. The method is document-oriented in its communication. Carl had first to get an application form. This is the schema (Xsd) for the request parameter of the method. He acquires this (and other thing such as the name of the methods that the organization has and the returning schemas) from TSV. (In Visual Studio .NET it could be done by adding a Web Reference to a project.)
When he has the schema for the request, he starts to fill out it. In .NET this is usually done by instantiate an object and assign values to its properties. When he has finished this, he sends the request to Greta.
The first thing that RenewDrivingLicense do is to validate the request. And it validates the request according to the same schema that Carl used to make the request. (Other validations could also be done here as well.) I'm sorry to say that these validation functions are not automatically done for us. We have to build them ourselves. But do not despair; they are rather simple to build. Here is a good example.
After the validation the real work begins. This work is complete hidden for Carl. This is the internal part of the method.
In our example this work turns out well and the method (or Greta) gets the schema that defines the response from the method. This could include some conversions of the returning data.
This object is returned to Carl and everybody is happy thereafter.
The Wsdl describes the method and its parameters. Xsd is used to describe the data that will be communicated.