Using Timestamp Filters

The remaining filter we need to look at in this chapter is the Timestamp filter. Of the filters that are handled in WSE, it has the most basic task. The output filter adds the Timestamp SOAP header using the details in the request SoapContext, and the input filter checks that the Timestamp SOAP header is correctly formatted and raises an exception if the header is incorrect or if the message has expired.

Most of the work accomplished by the Timestamp filters is automatic, and the only thing you can really change is the time-to-live (TTL) setting for a message. The time the message is created and the time it expires are added to the SOAP message by the output filter, and the input filter checks that the expiry time is not before the current time.

We’ll show the use of the Timestamp filters by building a simple application that allows the TTL for the message to be specified. This application uses the Timestamp Web service at http://localhost/wscr/13/timestampws.asmx. This Web service has one method, Time, that returns the Timestamp details from the received message as a string.

This Web service will automatically reject expired messages; by modifying the TTL of the message to a relatively small value, we can cause the message to be rejected by the Web service.

Note

Bear in mind two issues when you work with the Timestamp filters. First, all times are converted from local time to Coordinated Universal Time (UTC) format before they’re used. For example, if the machine you’re using is in Seattle (eight hours behind UTC), when you look at the time in the SOAP header it will appear eight hours ahead of local time.

The second issue is that all times are based on the time of the machines involved and not on some magical Internet time—the filters always assume that the time on the local machine is correct. Problems can arise if the machines are set to the incorrect time or time zone. If, after conversion to UTC, the times on the two machines are more than five minutes apart, you’ll have a problem—the default TTL for a message is five minutes, and all messages will appear to have expired.

One solution is to ensure that the time zone on the machines is set correctly and then to synchronize the machine time with one of the Internet time servers. You can do this easily in Microsoft Windows XP and Windows 2003 Server.

If you open the TimestampClient application in the sample code, you’ll see yet another simple form, as shown in Figure 13-9. This one allows the entry of the TTL value for the call and offers a Tell Me button that makes the call to the Web service.

Figure 13-9: The TimestampClient application

The TTL value in the text box is set at 300000 milliseconds, or 5 minutes. This is the default value used by WSE; we’ve also used this as the default value on the form.

When the Tell Me button is clicked, the first thing we do is create an instance of the WSE-enabled version of the proxy:

TimestampWSWse proxy = new TimestampWSWse();

We then enclose the rest of the code for the method in a try/catch block so any exceptions that are raised are caught and displayed to the user. The TTL value for the request is set by parsing the value in the text box as an integer and setting the Timestamp.Ttl property of the request SoapContext. We then make the call to the Time method of the Web service as normal:

try {     // set the TTL of the request     proxy.RequestSoapContext.Timestamp.Ttl = int.Parse(txtTTL.Text);     // make the remote call     MessageBox.Show(proxy.Time(), "Returned message"); } catch(Exception error) {     MessageBox.Show(error.Message,"Error!!"); }

On the server, we first define the variables we need to use. We create a string, strReturn, to hold the message we’re returning and a SoapContext object, reqCon, that is initialized to the current request SoapContext:

string strReturn; SoapContext reqCon = HttpSoapContext.RequestContext;

We then use various properties of the Timestamp object returned from the Timestamp property of the reqCon object to extract the timestamp details from the incoming SOAP message. The Timestamp object has Created and Expires properties that return the relevant times. We use these to construct a “created at X, received at Y, would have expired at Z” message and return this to the caller:

// extract the details from the message strReturn = "The message was created at " +     reqCon.Timestamp.Created.ToString() + ", "; strReturn = strReturn + "received at " + DateTime.Now.ToString() + " "; strReturn = strReturn + "and would have expired at " +     reqCon.Timestamp.Expires.ToString() + ".\n\n";

Two outcomes are possible from the Timestamp filters when we make a call to a Web service—the message passes through the filters without any problems or the message has expired and an exception is raised by the filter. We can simulate both of these scenarios using the TimestampClient application.

If we accept the default value of 300000 for the TTL value and click the Tell Me button, the Web service is called and a string is returned to the client, as shown in Figure 13-10.

Figure 13-10: Message returned showing the Timestamp details

As you can see from Figure 13-10, the message was created at 11:39:05 on March 14, 2003. It would have expired five minutes later were it not for the fact that it was received at 11:39:22, 17 seconds after it was sent. You can see the created and expired details in this extract from the SOAP header:

<wsu:Timestamp xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">   <wsu:Created>2003-03-14T11:39:05Z</wsu:Created>    <wsu:Expires>2003-03-14T11:44:05Z</wsu:Expires>  </wsu:Timestamp>

The difference between the created and received times might seem long for such a simple request, but it was affected by two things. The server that the Web service is running on is about 10 seconds ahead of the machine on which the client was executed. It was also the first time the Web service was actually called, so extra overhead was incurred due to the compilation of the code on the server. A second click of the Tell Me button yielded a much more respectable 12-second difference (about 2 seconds if you ignore the 10-second difference in the clocks on the two machines).

You’ve seen what happens if the message is received within the specified TTL; now let’s see what happens if the message has expired when it is received by the server. We can easily do this by specifying a very low value for the TTL. My personal favorite is 1— no request will ever take 1 millisecond to be transported and decoded.

Why not use 0 as the TTL? If you specify 0 as the TTL, you’re not specifying a TTL of 0 milliseconds—you’re actually specifying that you don’t have a TTL. If you set a TTL of 0, you don’t generate a <wsu:Expires> element—as you can see if you look at a fragment from the SOAP message that’s generated:

<wsu:Timestamp xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">   <wsu:Created>2003-03-14T11:42:38Z </wsu:Created>  </wsu:Timestamp>

And if you look at the message returned by the Web service, you can see that the expiration date has defaulted to an arbitrary value of December 31, 9999, at 23:59:59. You can see this in Figure 13-11.

Figure 13-11: Timestamp details with no expiration date

After that digression, we still haven’t seen an expired message being rejected. Set the TTL to 1 and click the Tell Me button. As you can see in Figure 13-12, the message has been rejected and a TimestampFault exception thrown.

Figure 13-12: An expired message throws a TimestampFault exception.

We have one further thing to cover regarding Timestamps. When you route messages, the Timestamp filters add <wsu:Received> elements for each router that the message passes through. We’ll cover routing in Chapter 14, and we’ll also look at this aspect of the Timestamp filters there.