Presentation Model

As I mentioned earlier, there is no presentation layer in a Web service. However, this does not mean that our service can't offer to play a role in its own presentation. A service can play an active role by offering assistance with styling, validation, and even content. It can also serve a passive role by not offering any additional data. The presentation model defines the services available for its presentation. These services typically take the form of content or instructions.

Even though the consumer dictates a service's participation in the presentation layer, any assistance in this area is usually welcome. If a consumer is given an option between two Web services, with all other criteria being equal, the one offering the most value to their services usually distinguishes itself. Presentation services are one of the most obvious means for adding value to your Web services.

A provider's offering assistance in the presentation also means that a consumer is less likely to freelance while utilizing your service. It leaves less room for a consumer to implement your services poorly or incorrectly. Because you are the creator and owner of the service, you should know the potential issues or pitfalls in the process or function you are providing, and this is one way of passing that expertise on to your consumers.

Designing the presentation model for your Web services is a two-step process. The first step is to determine the exposure level of the service itself. When I use the term exposure, I am referring to the exposure to the end user. Will the service ever have direct interaction with an end user or simply be a process for back end system use? This determination then leads to the next step, defining the presentation services.

An application has to have a user interface provided by at least one of the systems involved, either the consumer or the service itself. Usually, it will fall upon the consumer, but the service can provide value to the consumer in this area. Your presentation model will help you determine what the appropriate offerings might be from the service side and whether they are worthwhile.

You may often want to support different exposure levels for your Web service. You can either design a single complex presentation model or split the functionality between separate models. The difference in the presentation model is merely semantics, because either way you are providing the same service options. This decision does, however, affect your interface model, which we discuss in the next section.

The presentation model might be the hardest one to bring closure to because of the open-slate nature of the Web and the presentation of Web-based applications. Your presentation model will consist of a series of storyboards and document maps that illustrate your presentation services. Just like the presentation itself, the presentation model is basically complete once you are satisfied with the decisions you have made.

Exposure Level

The first step to defining your presentation model is identifying the exposure level for your service. This is almost like doing a feasibility study on how your service should and/or could be used by consumers. A Web service is always called directly by a system, not a user. That system may consume the service in the background, with no knowledge by the user, or the system may expose the service through an application's presentation layer. The service is consumed in exactly the same way in either case, but what the consumer does with the service is very different.

The presentation of a Web service to a user is the responsibility of the consumer, but there may be some appropriate information that the service could provide or reference through its response to assist the application. The use of that information is always optional, but, if the value is provided, some consumer will probably utilize it to reduce development and deployment time.

The exposure-level spectrum has two extreme sides: masked and isolated. The blending of these two extremes generates the most powerful model, the embedded service. Often, a Web service has the potential to fill various roles in different applications. The exception might be if you provide a service that is always part of a larger automated process. Even then, you might be surprised by the possibilities a consumer finds for your service independently.

Masked Web Services

Web services that are used for background processes or offline system processes are basically masked, or hidden, from any user. Such a service is integrated seamlessly, and the application presents no direct output of the service. Such Web services fill the same role as any other business object in an application. (See Figure 5-1.)

Figure 5-1: Masked Web service usage in an application

Experienced developers will recognize this model as something that is currently used to implement applications without Web services. Any of the established remote invocation methods could achieve this same result. However, Web services can facilitate a more open implementation to this application model because of its use of open standards. Services can be exposed over the Internet through Java RMI, but they would be accessible only to Java clients. This is an issue if you want to allow applications outside of Java to interact with your service. The need for exposing a remote service as a Web service will stem from your intended target consumer base.

The presentation model for a masked Web service is obviously simple, because its service and response require no presentation content. Thus, the masked service is the quickest model to define. Although such a model does not fully exploit the capabilities of Web services, it can be very effective in achieving an integration solution.

A status Web service is a good example of a masked service. If an application wants to check the status of an order, the inventory of an item, or the status of some request, a masked Web service is very appropriate. In this case, a user may not even be involved if the application is an automated routine to periodically "ping" the status. The application is merely consuming a service, and the expectations of it are very straightforward: be available and accurate.

As consumers of Web services, this service type may not be very appealing to us. If we want to implement a masked Web service as a component of an end user application, we are on our own for defining the presentation of the service, if it is necessary. The service is providing us with raw data. Obviously the more data that is exposed, the greater the effort the consumer generally has to put into its presentation, especially if it needs structure (tables or spacing).

When exposing a lot of data through a masked Web service, the service provider may want to reassess their chosen model if the provider can foresee the need to expose it directly to a user. The provider's objectives should be not only to identify the intent with the service but also to foresee what consumers might do with it. Then a model, or models, can be built that will most effectively accommodate those needs. You can provide separate services that address each need or one service that meets both. These approaches are discussed in more detail in the interface model description. The key in this section is to recognize the fundamental difference between a masked Web service and other Web services models, and that sometimes implementing more than one model is necessary.

Another feature of the masked service is that it usually does not have to incorporate any workflow or processes across multiple calls. Because these services are usually part of an automated process, they usually involve only a single request and response, and not a series of requests. This again makes masked services some of the quicker and easier Web services to develop and implement.

Isolated Web Services

The presentation model for an isolated Web services is the antithesis of the model for masked Web services. This model exposes data directly to the user by being passed through the consumer. This can manifest itself via input fields, a result set, or both. This data requires some formatting and/or styling to align with the rest of the application if the consumer wants to maintain a consistent look and feel.

The difference between the isolated model and others lies in the handling of the service itself. Whereas other service models are incorporated in an application's process, an isolated Web service is given a virtual space in which to interact with the user directly. Although all information passes through the consumer's application server, with an isolated model the consumer takes a more hands-off approach to the actual process and functionality. You can think of this concept as piping a protocol directly to the user through the consumer's application. (See Figure 5-2.)

Figure 5-2: Interaction with a user by an isolated Web service

For a consumer, implementing Web services in an isolated model is not something to be taken lightly because such an implementation directly exposes content provided by a third party. Such a partnership requires some trust as well as a tight design to help insulate the application from any problems the service might have. For instance, if the Web service is unavailable, what will the repercussions in the application be? What will the result be if the Web service starts returning invalid responses? You need to keep the outcome of such situations from being catastrophic, but you also need to be careful when selecting service providers with which to establish such a partnership.

Note 

This is not meant to scare you away from implementing isolated services; they can be very effective for consuming Web services. Isolated services just require a solid business partnership and should not be done haphazardly.

Web developers may recognize that isolated services function much the same as content in a frameset reference. Instead of embedding the data directly, Web services give the consumer the opportunity to have some level of control over the entire presentation. In this virtual frame of the Web service, the consumer can apply some formatting or, more importantly, handle any error conditions.

Caution 

In evaluating whether you are working with a masked or an isolated model, remember to consider each call individually. If you are considering a sequence of calls, it is an easy trap to start contemplating the requests that are made based on information provided by another Web service call. Each service call can have only one model, and the type of response provided is determined through that model.

This leads us to another decision that must be made once the isolated presentation model is designated. Will the consumer build the interface for collecting the data from the end user, or will the provider add this as a value-added service? If the provider adds this functionality to its Web service, a single transaction then takes two requests, not one. (See Figure 5-3.) One call retrieves the data defining the user input interface, and a second submits this information to the provider (the original service). This is a less efficient solution due to the extra call, but it automatically updates if a change is made to the service.

Figure 5-3: An input interface provided by an isolated Web service

If the consumer takes ownership of the collection of input data from the user, it is not automatically updated if the provider makes changes to the service. This creates more maintenance work for the consumer, but is less effort for the provider. (See Figure 5-4.)

Figure 5-4: An input interface provided by the consumer

Because Web services are such a new concept, consumers might initially feel very comfortable implementing isolated services as their first step in Web service applications. However, once they implement them and become more comfortable, they are likely to want more input and control of the process. They might start peeling back some of the service's offerings and implementing them to more closely match their exact needs. For consumers to achieve the results they want, the presentation model will have to change. Your responses will have to act much more as enablers for presenting data to a user, so that consumers can effectively embed them within their applications.

Embedded Web Services

Once the solution matures, most Web services will likely fall in the category of embedded services. This model takes full advantage of the capabilities available through the Web services architecture to provide an integrated application comprising many independent components. The shared ownership of an application interface is a fairly new and radical concept, so we will spend some time discussing this model.

Note 

Don't trivialize this shared UI concept by equating it to an HTML frameset UI. In a frameset application, multiple content providers own sections of the interface in physically independent sections of the screen. This is only slightly more effective than having multiple browsers open and connected to different applications. In this shared UI, the consumer builds the interface out of content they have and what the provider is passing or referencing through their Web service response.

When you provide or consume Web services with an embedded presentation model, you must decide among several available options. This stems from the different levels of integration available through a Web service. These should be thought of not as clear, distinct levels, but as a blending of different ownership areas that result in the application's processes and interface. Fortunately, these ownership areas can often be directly tied to pieces of the presentation layer. The embedded presentation model should identify which roles the service provides.

For instance, if your Web service requires information from the end user, you can provide the code to produce the HTML form or enough property information for the consumer to build a valid form in the application. Either option is technically feasible, so it comes down to an issue of what you think a consumer of your service will want and what will provide the most value. You can provide all of these services and allow consumers to make their own selection, but there may not be justification for the work involved to do so.

Let's walk through a sample Web service and address the appropriate options available to the provider. We will refer back to our hotel availability scenario and take the perspective of the hotel owner developing a Web service in the reservation system. Our target audience will be online travel sites that provide access to airlines, hotels, and rental cars.

As the hotel owner, we want to provide a list of the available rooms that match a set of criteria. Our goals are to (1) have a quick turnaround of the information, (2) produce an accurate match to the criteria provided, and (3) stand out in a listing that includes competitors. We know that the travel site works with several hotels, so they will probably not want our participation in defining the input interface for the end user. That means we will have to work with the criteria they have provided through their form. Of course, by offering to accept additional criteria through our Web service, we could possibly entice the consumer to extend their input interface to take fuller advantage of our service.

Otherwise, our main focus would likely be the presentation of our resulting information. We could provide some link references or font treatment to our data. We might even be able to include some small graphics. Getting the travel site to respect the information we provide may take some consideration in our business agreement, but we could provide it nonetheless. The key consideration is not to overwhelm the consumer with extraneous data that will never be utilized or, even worse, that interferes with the presentation of our data.

Caution 

Making a content-related decision is much safer when you are providing a service for the first time. Making changes after deployment can be harmful where the presentation model is concerned.We will take a closer look at maintaining some measure of backward compatibility in Chapter 6.

So the service's presentation model could include font treatment, graphic references, and link references. Including this information may result in a presentation of hotel information on the travel site that looks like Figure 5-5. Notice how the Milton Hotel stands out from the other hotels.

Figure 5-5: Travel site results screen with a distinctive listing

Keep in mind that the consumer application may choose to enforce the treatment of all hotels as equals, in which case the results will look no different from before the integration of our presentation services. (See Figure 5-6.)

Figure 5-6: Travel site results screen with generic listings

This may seem fairly straightforward, but this example takes into account only one consumer type. Let's take a look at the same Web service in a different scenario. Say we have established an exclusive agreement with a specific airline that will embed our hotel availability service on its Web site when users make an airline reservation. To facilitate this partnership, we want to make it as easy as possible for the airline to use our service. To this end, we want to provide the necessary constructs for collecting and validating the hotel search criteria. Because we also have an exclusive presence in the application, we won't care about standing out and probably want to blend in with the look of the entire site. Our agreement may also be such that all activity takes place through the airline's site, so links may not be appropriate. This service's presentation model would then consist of input form data and validation code.

These two scenarios will inevitably cause someone to ask whether these offerings are two Web services or one. The interface model described in the next section addresses this very important issue. The other question we might ask is what content to provide once we know what presentation model our Web service will have.

Presentation Services

Defining the presentation services of a Web service is where the meat of the presentation model resides. Our determination of the service's exposure level helped us to identify the appropriate environments for our Web service. Now the presentation services themselves will define what offerings we will provide to assist the consumer during implementation.

Note 

Sometimes I will refer to the support services of a Web service. This might seem confusing at first, but it refers to the additional functionality that a Web service provider makes available to its consumers. The Web service itself is simply the core functionality to access an application with no extra consideration for the consumer's implementation process.

Presentation services are appropriate only for embedded or isolated models, because masked services don't interact with users. Between those two, the extent of these offerings can vary quite a bit. An isolated service basically provides a lot of data to simulate the application on the server (not too different from any other Web-based interface). It would be overkill for an embedded service to provide that much information, so instead it provides more instruction-oriented services to the consumer.

These two approaches, data and instructions, are the two mechanisms for providing services on the presentation layer. The distinction between these two can sometimes blur, especially when client-side scripts are involved. The easiest way to draw this line is between the target audiences. Instructions are meant explicitly for the consuming application, whereas data is meant for the end user (or the user's browser). Although data is more useful on a passthrough basis, instructions require more implementation time and knowledge on the consumer's part. As I mentioned earlier, the direct approach is initially more appealing, but ultimately the instruction set should be more popular with consumers because it is less of an all-or-nothing approach.

We can provide services in the presentation layer in three different areas: content, style, and validation. Each of these areas may or may not be provided, depending on your objectives. If provided, each of these can be exposed through either a data or instruction delivery. The end result could look the exact same for both delivery methods, but the paths for getting there would be very different. The data-centric method is more appropriate for isolated services, whereas the instruction-centric method is usually necessary for an embedded service. Figure 5-7 should help you visualize the relationship between the different content areas and these two mechanisms for delivery. We will refer back to this relationship as we discuss various presentation services.

Figure 5-7: Presentation service options

When identifying the services you will provide, you need to consider not only what but also how. Do you provide them as raw data or as instructions to be utilized by the consumer? Because the latter option provides more flexibility, you are less likely to provide content, style, or validation through both data and instructions. Once consumers make the move to accommodate an instruction-oriented delivery, they will want to take advantage of that and get away from blindly accepting presentation data from the service.

It is also logical to make the decision of either providing or not providing information in each area in total. For instance, if you are going to provide some validation, why not provide total validation, at least on a request-by-request basis?

Content-Oriented Services

The distinction between content and style can sometimes be hard to make. This is meant to be more of a logical grouping than physical, because any presentation data can arguably be classified as content. My reference to content is meant to identify the data consisting of the user interface itself. This can take the form of HTML, text, graphics, or links. This is all the data that is intended to be used to build or enhance the actual end user experience specific to the Web service's functionality.

Note 

Links play an important part in all three areas in an instruction-based presentation model. The links I refer to here are specifically meant for direct exposure to an end user, not for use by the consuming application.

Because a Web service responds to a single request, we have only one stream of XML to work with to provide presentation services. Furthermore, there are currently no adopted mechanisms to include binary data in XML, so it is not possible to directly include any image data. Fortunately, because the nature of Web services requires Internet access (or at least access to some network), we can use linking mechanisms to reference external content when necessary. We will address this issue as it applies specifically to each area.

Data-Oriented Services

Passing content through raw data is a simple extension to creating HTML presentations. The most important factor is that all data must be XML compliant. This is especially important for the content portion of your presentation support services, because you will often pass HTML code in your Web services response.

Tip 

If you are going to pursue this approach, you should attempt to get familiar with XHTML and adopt its formatting rules to make this task easier.

One limitation of providing content through raw data via Web services is the lack of support for binary data. This means that actual images and other non-ASCII data cannot be passed back to the consumer. One workaround is to provide separate data to your partners via templates or content. Templates are a good approach to getting consumers up and running quickly, but providing actual content can be dangerous. Although this approach may suit your needs initially, providing content manually will probably turn into the same maintenance nightmare that sharing content for Web applications is today.

A better solution is to reference graphics and other binary data on your systems. Although this approach makes the application depend more on the availability and performance of external systems, Web services in general create that dependency. This approach will make for a cleaner implementation that is more dynamic and easier to maintain, true to the vision for Web services.

Let's take a look at a scenario for providing content through your presentation services. In reference to our hotel scenario, let's say we have an exclusive agreement with a car rental company to offer room availability searches on its site. This might be a good fit for an isolated model of our Web service that would require us to provide our services through a data-oriented approach.

Assume for now that the car rental company is going to collect the necessary information to check the room availability via our Web service. We then need to provide a clean output of our data so the company can "drop" it into its application page. Our basic response without any presentation services would look something like this:

 <hotelAvailability xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance" >      <date>2001-08-05</date>      <hotel>           <address>                <street>1500 Campbell Road</street>                <city>Richarson</city>           </address>           <rating>3</rating>           <distance measurement="miles">1</distance>           <bedSize>King</bedSize>           <cost>79.99</cost>           <nonsmoking>Yes</nonsmoking>      </hotel>      <hotel>            <address>                 <street>1730 Plano Parkway</street>                 <city>Plano</city>            </address>            <rating>3</rating>            <distance measurement="miles">1.5</distance>            <bedSize>Queen</bedSize>            <cost>69.99</cost>            <nonsmoking>Yes</nonsmoking>      </hotel> </hotelAvailability> 

Although this data represents everything we need for the Web service response, the consumer cannot use it as is. Because this information is presented directly to the user, we should provide all the information's formatting. By doing this we, the provider, control how the information looks. It is then up to the consumer to make the information look like it belongs in their application.

There are actually several different approaches to adding content to data. One approach is to simply include the stylesheet as a reference at the top of the XML document. The second approach is to embed the content directly in the XML document. In either case, you use the same stylesheet for formatting the data. The only difference is where the transformation is applied: by the provider before the response is sent, or by the consumer after the response is received. Either way works, but the former places fewer demands on the consumer and is more efficient overall because it likely reduces the overall handling of the data throughout the Web services process. This isn't ideal because the usability of the data in the payload decreases, but the data-oriented approach by nature is not ideal.

Our stylesheet will be designed to loop through all the results and provide some structure for the result set, as shown here:

 <xsl:stylesheet version="1.0"xmlns:xsl="http://www.w3.org/1999/XSL/Transform">      <xsl:template match="/" name="rootTemplate">      <hotelAvailability>           <date>Available hotels for <xsl:value-of select=             "/hotelAvailability/date"/></date>           <p/>           <table border="1"><tr>                <td>Rating</td>                <td>Distance</td>                <td>Cost</td>                <td>BedSize</td>                <td>City</td></tr>                <xsl:for-each select="hotelAvailability/hotel">                     <tr>                          <td>                                <xsl:if test="rating>3"><img src="/books/4/149/1/html/2/http://                                  www.architectingwebservices.com/images/                                   star.gif" alt=""/></xsl:if>                                <xsl:if test="rating>2"><img src="/books/4/149/1/html/2/http://                                  www.architectingwebservices.com/images/                                  star.gif" alt=""/></xsl:if>                                <xsl:if test="rating>1"><img src="/books/4/149/1/html/2/http://                                  www.architectingwebservices.com/images/                                  star.gif" alt=""/></xsl:if>                                <img src="/books/4/149/1/html/2/star.gif" alt=""/>                          </td>                          <td><xsl:value-of select="distance"/></td>                          <td><xsl:value-of select="cost"/></td>                          <td><xsl:value-of select="bedSize"/></td>                          <td><xsl:value-of select="address/city"/></td>                     </tr>                </xsl:for-each>           </table>      </hotelAvailability>      </xsl:template> </xsl:stylesheet> 

Applying this template to our data produces the following XML-compliant output incorporating content in our response:

 <hotelAvailability>      <date>Available hotels for 2001-08-05</date><p/>      <table border="1">           <tr>                 <td>Rating</td>                 <td>Distance</td>                 <td>Cost</td>                 <td>BedSize</td>                 <td>City</td>           </tr>           <tr>                 <td>                      <img src="/books/4/149/1/html/2/http://www.architectingwebservices.com/images/                        star.gif" alt="" />                      <img src="/books/4/149/1/html/2/http://www.architectingwebservices.com/images/                        star.gif" alt="" />                      <img src="/books/4/149/1/html/2/http://www.architectingwebservices.com/images/                        star.gif" alt="" />                      <img src="/books/4/149/1/html/2/http://www.architectingwebservices.com/images/                        star.gif" alt="" />                  </td>                  <td>1</td>                  <td>79.99</td>                  <td>King</td>                  <td>Richarson</td>           </tr>           <tr>                  <td>                       <img src="/books/4/149/1/html/2/http://www.architectingwebservices.com/images/                         star.gif" alt="" />                       <img src="/books/4/149/1/html/2/http://www.architectingwebservices.com/images/                         star.gif" alt="" />                       <img src="/books/4/149/1/html/2/http://www.architectingwebservices.com/images/                         star.gif" alt="" />                  </td>                  <td>2</td>                  <td>69.99</td>                  <td>Queen</td>                  <td>Plano</td>           </tr>      </table> </hotelAvailability> 

When placed in a Web page by the consumer, the presentation is very simple, but it is completely functional and provides a basic look that allows the consumer to use the output as is. (See Figure 5-8.)

Figure 5-8: Output of Web service result with content

Of course, this could look a little more appealing! After completing the discussion of content, I will look at providing style information, which can help the presentation immensely.

Instruction-Oriented Services

When we need to merely assist the consumer with the presentation of our Web services, an instruction-oriented approach is more appropriate. Through this, we can pass along important knowledge specific to the data, empowering the consumer to handle it appropriately. This allows the consumer to make intelligent decisions about how to present the information, or perhaps even whether to present it. This also gives the consumer a better command of the data, which is what most consumers prefer once they start utilizing Web services.

Let's return to our hotel availability scenario where we are working with a portal site getting information from many hotel chains. This should be an experienced consumer that will want total control over the presentation of the information we give it. The consumer may filter the information to use only pieces of it or may change the representation of the information to suit the consumer's needs, perhaps making the responses of several chains look alike.

We will start with the same basic response of our service and build from that. Let's say we want to provide our logo and a picture of each hotel, a link to more information about each hotel, and the number of room matches we are returning. The pictures and links are obvious efforts to provide visual aids and more detailed information for selecting a hotel. The number of matches is something that simply helps out the consumer so the consumer doesn't have to come up with a counting algorithm. This number is important because the consumer may have to dynamically determine the layout based on the amount of information it receives. Blindly looping through a document can be risky when you are trying to maintain a good user interface.

For the logo, we will simply add an additional field to the data set called logo. This is actually a reference to the image on our site. Each hotel result also includes an image reference as well as a link element. For the number of matches, we will add another child element at the root. With these services, the resulting XML payload would look something like this:

 <hotelAvailability>       <date>2001-08-05</date>       <logo>http://www.milton.com/logo.gif</logo>       <numberMatches>2</numberMatches>       <hotel>             <link>http://www.milton.com/richarson/info.htm</link>             <picture>http://www.milton.com/richarson/image.gif</picture>             <address>                  <street>1500 Campbell Road</street>                  <city>Richarson</city>             </address>             <rating>3</rating>             <distance measurement="miles">1</distance>             <bedSize>King</bedSize>             <cost>79.99</cost>             <nonsmoking>Yes</nonsmoking>       </hotel>       <hotel>             <link>http://www.milton.com/plano/info.htm</link>             <picture>http://www.milton.com/plano/info.gif</picture>             <address>                  <street>1730 Plano Parkway</street>                 <city>Plano</city>           </address>           <rating>3</rating>           <distance measurement="miles">1.5</distance>           <bedSize>Queen</bedSize>           <cost>69.99</cost>           <nonsmoking>Yes</nonsmoking>      </hotel> </hotelAvailability> 

By providing the content in this manner, we are empowering the consumer to make the choices about what gets used and what does not. Making the most of this avenue will be important as the industry matures in its use of Web services.

Caution 

Techniques are in development that allow for binary data to be embedded within XML documents. Although this functionality may have practical uses, this would not be one of them. Attaching large files in XML that could be referenced externally would not only be presumptuous of the consumer's needs, but also terribly inefficient in this era of Internet connectivity.

In this case, we provide images, links, and data information. The consumer can use this information in any number of ways that will meet its needs. Figures 5-9 and 5-10 are two completely different presentations, both based on this same payload of data.

Figure 5-9: Presentation scenario 1

Figure 5-10: Presentation scenario 2

You should have a feel now for the different types of content you can provide for your Web services and how to go about providing them. To really tailor the presentation, though, you need to take advantage of styles. Style can be an underrated aspect of a Web application that distinguishes itself from others by looking professional.

Style

Even with quality content, a presentation may look less than professional without some styling. You could easily consider style as part of the content, but I will treat style and content separately because that is the tendency of the industry. This has really come about through the cascading style sheet (CSS) standard, which gives developers the ability to isolate the two. This way, a designer can tweak certain aspects of Web interfaces en masse without disturbing any of the functionality. This same approach is also useful for developing Web services and their user interfaces.

There can also be some differences in how these two areas are handled because of the nature of style data ownership. If the ownership of content is outside the control of the service provider, the styling of that content is even more so. Because there are mechanisms for affecting the formatting of information externally (CSS and XSL), even prestyled data is not safe from changes because it isn't critical to the service being provided. Keep in mind that these are support services we are discussing, and your primary goal should be delivering an effective Web service. Afterward, you can provide these features, making certain they don't interfere with your original goal. Forcing styles on consumers that may not match their needs could amount to enough interference that they look elsewhere for their Web services.

It is easy to confuse the concepts of style and content if you do not have some design experience. Anything that does not communicate any information on its own falls in the category of style data. This includes colors, font types, backgrounds, and spacing. Images and layouts fall in that gray area that may be hard to discern because their value is a little harder to determine. Images you present may or may not be communicating something. In the hotel availability screen shot (Figure 5-8), the images represent a rating of either three or four stars. It is a visualization of data, so taking it away would affect the information actually communicated to the user. Likewise, the table layout allows for a stacked view of like data. If it were all displayed in a single row, would the information have been communicated correctly? Rather than debate these issues, I will simply make my own qualifications, as you are likely to do on your own. The important issue here is that you determine what you are going to provide to your consumers and how you will go about doing it.

Along those lines, just as you can with content, you can choose to provide actual formatted data or simply aid in the formatting through instructions. Let's look at the difference between the two for this type of information.

Data-Oriented Style

If you are passing straight format and styling data through to the consumer, then you are likely passing the content itself directly. In this case, it is simple enough to add the appropriate information in your payload. To enhance our star-rated availability listing, we could modify the payload by adding font treatments. However, this does take the payload one step further down the road to strictly presentation information, and therefore less and less use on a data level to the consumer. It also makes your service work a little harder to build more data into the payload directly.

A better option for supplying such data is to reference a CSS in your payload. This means that the end user's browser references the style data, bypassing the consumer completely, placing less demand on our service and the application. I'm not going to go into detail about CSS, but a single line added to our payload provides this reference just like any HTML page:

 <link rel="stylesheet" type="text/css" href="   http://www.architectingwebservices.com/mystyle.css"/> 

Some information cannot be communicated through a CSS, and that you must incorporate in your payloads. Just as we included image links in our example, we have to do the same thing with any objects we want to include. Any effects generated via a client-side script also fall outside the capabilities of CSS and must be included in the payload or referenced through other mechanisms. I did not discuss that in the content section, but will in the validation section because client-side script plays such a significant role there.

Instruction-Oriented Style

Instructions for styling a Web service presentation may or may not make sense depending on what you are trying to achieve. This is because the complexity around implementing the instructions is greater than that to actually change inline styling. For instance, if you provide instructions to consumers on what font a particular section of text should be, the consumer has to parse that information and implement a method for applying it. If the text comes predefined, the consumer just has to implement a method for applying the font it chooses.

However, there are some cases in which this is a good approach. If the style information would take up a lot of bandwidth (which is the case with many script-driven browser events), and not many consumers are likely to utilize it, it would be both an inconvenience and a drain on your resources as the provider. By providing instructions instead of applying the actual format to your payload, you have a more flexible offering for a wider range of uses.

This may sound similar to using CSS, but it actually abstracts it one step further. Including an actual stylesheet link means that you pass presentation content directly through your payload. Turning this reference into an instruction means providing the reference as a separate element in your payload. In our hotel availability scenario, we were originally passing raw data in the payload. By adding a stylesheet element, consumers can decide whether to reference it without being too encumbered if they choose not to. Below is an example of how you might present a stylesheet link in a Web services response:

 ... <hotelAvailability>      <date>2001-08-05</date>      <stylesheet>http://www.architectingwebservices.com/mystyle.css        </stylesheet>      <hotel> ... 

If you were the consumer of this Web service, you could then build the CSS-valid reference to the stylesheet by writing the following XSLT code:

 <link rel="stylesheet" type="text/css">      <xsl:attribute name="href">           <xsl:value-of select="/hotelAvailability/stylesheet"/>      </xsl:attribute> </link> 

And just like that you have provided and consumed style information through an instruction mechanism. Now that we have covered both content and style information, let's look at how to provide the appropriate data for validation.

Validation

Whenever you think of validation in an application, you probably think in terms of data inputs. In Web applications, you probably think more specifically about user inputs. This is exactly the kind of validation we are talking about here. It has a slightly different meaning here, though, because we are specifically concerned with the user data that will be passed on to a Web service. If we have a Web application that takes in user information for placing an order, we will want to collect an entire set of data, including payment, address, and contact information. If we have a Web service that validates address information, we are concerned with only a subset of the data. This is the section where the Web service may assist with the validation.

This situation is unique from any other discussed previously because we are providing assistance before the actual consumption of our Web service. We are validating the user inputs for collecting the appropriate data to use our service correctly. This actually extends the scope of our service and is basically a service in and of itself. Implementing this turns any Web service request into two service requests. We will look in the next section at the affect this has on the interface of our Web service.

Expanding on our scenario a little more, let's say we collect all user data through a single screen (see Figure 5-11). I will simplify the example by saying our Web service validates only U.S. addresses, so it will accept the following inputs:

• Address line 1

• Address line 2

• Address line 3

• City

• State

• ZIP code

Figure 5-11: Purchase order screen

The service responds with simply a true or false result. Our focus, however, is on the inputs for the service. The XML document sent to the service needs to take the following form:

 <validationRequest>       <address1/>       <address2/>      <address3/>      <city/>      <state/>      <zipCode/> </validationRequest> 

How long can the address and city lines be? Does the state field accept the entire name or standard two-character abbreviations? Does the ZIP code accept +four codes or just the basic five-digit codes? Can I have an address2 element if address1 is blank? Some of these questions can be answered by a schema, but some cannot. A service must provide the details to these answers through another mechanism.

What we are actually concerned with here is the next step after this information is communicated. How do you enforce these rules with the end user? Certainly, the consumer could hardcode the presentation to do this, but that is both inflexible and tedious. If the Web service expands its capacity to support additional data, every consumer would have to make a change to adapt. One solution would be to have the Web service actually provide the necessary data or information to facilitate the enforcing of these rules.

When you provide validation on any Web application, you have three levels you can work with (see Figure 5-12). The first level (1) is in the import forms themselves. With HTML forms, you can limit options through drop-down menus, radio buttons, and check boxes and limit data lengths in text fields. The second level (2) is client-side validation. This adds a little bit of intelligence to the client to perform slightly more sophisticated validation without hitting the application server. Finally, the third level (3) is where logic on an application server can perform very detailed validation. In Web services, this can extrapolate to two levels when you consider that the consumer's application can perform some validation (3a) and the Web service itself (3b) also performs some level of validation.

Figure 5-12: Validation levels in a Web service application

Data-Oriented Validation

In a data-oriented approach, a Web service can provide the entire HTML form and client-side script necessary to facilitate and enforce the entire data-entry process. This is the simple way out and asks the consumer to place quite a bit of trust in the Web service provider.

In the case of client-side script, you actually have some choices in how to expose it. Just as with the CSS discussed in the previous section, script documents can be referenced externally or embedded in the payload itself. Also like CSS, referencing scripts externally reduces the burden on the actual service, the consumer application, and the payload between them. Adding the standard external script reference in the presentation's payload achieves this. Just like a CSS reference, the user's browser references this information (as seen below) directly, bypassing the consumer's application and server.

 <SCRIPT type="text/javascript"   src="/books/4/149/1/html/2/http://www.architectingwebservices.com/validationscript.scr"/> 

Caution 

Take care when developing or utilizing client-side script in this new programming paradigm. The code could get assembled with other scripts, so try to avoid generic function names and global assignments to minimize conflicts.

As far as the consumer's application goes, a data-oriented approach can't do much to provide assistance, because any data is instruction based and not part of a passthrough system that the data-oriented approach facilitates. Instead, the next level of validation is the Web service itself.

Because the data from this approach is ultimately the user's interface, the end result of any implementation, let's go ahead and look at how to get there through an instruction-oriented approach.

Instruction-Oriented Validation

Instead of passing the data that will be delivered directly to the end result, most consumers want and appreciate a more cooperative methodology to delivering an effective, validating interface to the end user. This is the goal of the instruction-oriented approach. One of the first things to do as a provider is determine the ideal interface for collecting the data that your Web service will need. Remember, you should be the expert behind your service's functionality, and the consumer will be looking to you for guidance in how to expose it. Once you determine the interface, you can then figure out which pieces to validate and how to go about doing so.

Designing the "Ideal" User Interface

The interface for collecting data from an end user is typically presented through an HTML form. In that form, you can limit the options of the user up front. By limiting the range of information the interface collects, you can save some effort in validating certain situations. For instance, if you have a state field, it can simply be an open text field. Because the longest state name is South Carolina, you can limit the maximum length to 14 and set the size to accommodate the layout, as shown here:

 <INPUT type="text" name="state" maxlength="14" size="10"> 

However, doing this allows the user a lot of room for misspellings, which can be a real problem for your application and may require a second round of data entry for clarification. This will be inefficient for both the user and the system. A better method is to allow only a two-character field for the established state abbreviation, as shown here:

 <INPUT name="state" maxlength="2" size="2"> 

Even this allows some room for error, though. How many times will people incorrectly use AK for Arkansas? A drop-down list is ideal for further restricting the options, even though it does require a bigger payload for the user. Here we see the HTML for such an approach:

 <SELECT name="state">      <OPTION value="" selected></OPTION>      <OPTION value="AL">Alabama</OPTION>      ...      <OPTION value="WY">Wyoming</OPTION> </SELECT> 

With this approach, you can now design the ideal interface for your address verification service. We will make the addresses all match and allow up to 40 characters each. We will allow 30 characters for the city. In our ZIP code, we will support only a five-digit number, so we will define it as such. With these determinations, the entire presentation HTML code looks like this:

 <INPUT name="address1" maxlength="40" size="20"><br> <INPUT name="address2" maxlength="40" size="20"><br> <INPUT name="address3" maxlength="40" size="20"><br> <INPUT name="city" maxlength="30" size="20"><br> <SELECT name="state">      <OPTION value="" selected></OPTION>      <OPTION value="AL">Alabama</OPTION>      ...      <OPTION value="WY">Wyoming</OPTION> </SELECT><br> <INPUT name="zipcode" maxlength="5" size="5"> 

The breaks cause these form elements to align in a column, as you can see in Figure 5-13. Notice that there are no form tags or identification of the fields for the user. We are providing just the basic information necessary to aid with the collection of data. We could provide the appropriate copy for the consumer to use, but we would want to isolate that from this content so the consumer can make that choice.

Figure 5-13: Browser view of address verification form elements

Sharing the Interface with Consumers

Now that we understand the kind of assistance we can provide through the presentation, we need to develop a strategy for communicating this to the consumer. In the data-oriented approach, we would just pass it as is, but we don't want that approach for this more integrated effort. Let's also say, for the sake of argument, that this is a specialized list of state data. If it were simply a list of all 50 states (plus Washington, D.C., of course), the consumer could provide that interface simply enough. Our service may be a tax service that applies to only those states with income taxes, for instance. In this case, the consumer might prefer to defer to our service's ability to provide appropriate custom interface elements.

The effectiveness of our solution will depend largely on how easy it is for the consumer to integrate the information with the rest of the application. For that reason, simply passing back a chunk of XML-compliant HTML for the entire interface is probably not the ideal approach. Doing so would limit the consumer's ability to select the desired pieces or at least require more development and processing to segment it. So, at the very least, we want to break our elements into individual elements that the consumer can work with on a data level. Taking the presentation we designed earlier, the resulting document looks like this:

 <addressVerification>      <address1><input name="address1" maxlength="40" size="20"/></address1>      <address2><input name="address2" maxlength="40" size="20"/></address2>      <address3><input name="address3" maxlength="40" size="20"/></address3>      <city><input name="city" maxlength="30" size="20"/></city>      <state>           <select name="state">                <option value="" selected=""></option>                 <option value="AL">Alabama</option>                 ...                 <option value="WY">Wyoming</option>            </select>       </state>       <zipCode><input name="zipcode" maxlength="5" size="5"/></zipCode> </addressVerification> 

During the process we had to make our HTML XML-compliant and isolate each element on a data level. You might notice a little redundancy in the fact that our elements are essentially the name attribute of our form fields. We could eliminate this duplicated data, but the consumer application would then have to modify the code before displaying it. The benefit of streamlining the data does not outweigh the processing efficiency in this example, so I chose to leave it as is.

If bandwidth is a real concern of the consumer or service provider, an alternate method can be used for communicating this information through the use of reference links. We can segment the actual HTML code into separate documents, which the consumer can retrieve separately. This keeps the consumer from having to work with unnecessary data and does not prevent the consumer from using other presentation pieces. The following code might be the result of taking this approach:

 <addressVerification>      <address>http://www.architectingwebservices.com/interface/        address.xml</address>      <address>http://www.architectingwebservices.com/interface/        address.xml</address>      <address>http://www.architectingwebservices.com/interface/        address.xml</address>      <city>http://www.architectingwebservices.com/interface/        city.xml</city>      <state>http://www.architectingwebservices.com/interface/        state.xml</state>      <zipCode>http://www.architectingwebservices.com/interface/        zipCode.xml</zipCode> </addressVerification> 

Notice that all three addresses now reference one address file. In fact, all three addresses are now defined the same. The order of multiple address lines often does not matter. In that case, they can be treated the same. If we are talking strictly on a data level, there really is no difference between these fields.

However, for HTML forms, the elements must have unique names to keep the data from being concatenated and thus potentially extending beyond our maximum length of 40. If we are concerned about bandwidth bottlenecks, it might make sense to have the consumer modify the address line by adding the name properties as necessary for the consumer's presentation. This allows both the consumer and the service provider to treat them the same outside of the HTML code.

Adding Client-Side Script

To enforce a higher level of validation on the client, we will need to implement client-side script. This allows us to catch some basic user-entry errors such as invalid alphanumeric values and null fields. Catching this on the client side saves cycles on the server and is the preferred method of validation for any savvy developer.

This is what a client-side script for our address verification interface might look like:

 <script language="javascript">      function SubmitAddress() {          bValidAddress = true          if (document.form1.address.value == "")               alert("Please specify an Address.");          if (document.form1.city.value == "")               alert("Please specify a City.");          if (document.form1.state.value == "")               alert("Please specify a State.");          if (document.form1.zipcode.value == "")               alert("Please specify a Zip Code.");          ValidateZipType()          if (bValidAddress) {               // TODO: Submit Data to Application.          }      }      function ValidateZipType() {         if (document.form1.zipcode.value < "00100" ||             document.form1.zipcode.value> "99999")             alert("Please specify a valid ZipCode.");      } </script> 

Of course, this depends on a few more elements being added correctly to the form's presentation by either the service provider or the consumer. These are the elements that define the form and its name and the function call necessary on submission of the form. This information can be either wrapped around the entire presentation or contained in separate elements. This might be one solution:

 <formName>form1</formName> <validationFunction>SubmitAddress()</validationFunction> 

This can then be integrated into the application's presentation with the following XSL code:

 <form>      <xsl:attribute name="name"><xsl:value-of select="formName"/></xsl:attribute>      ...      <input type="submit">           <xsl:attribute name="onClick">                <xsl:value-of select="validationScript()"/>           </xsl:attribute>      </input> </form> 

The body of the form then resides between the form tag and the submit button. Of course, the consumer can certainly name the form, and in fact name it something different and reference that through the script. Editing script can get a bit tricky, however, because you then need to make the script XML compliant to use XSL.

Just as we did in supplying style instructions, we could provide a reference to the actual script through additional nodes. Instead of <stylesheet>, we could use a <script> tag that the consumer can easily process, as shown here:

 <script>      <xsl:attribute name="script/type">           <xsl:value-of select="text/javascript"/>      </xsl:attribute>      <xsl:attribute name="script/src">           <xsl:value-of select="http://www.architectingwebservices.com/             script.scr"/>      </xsl:attribute> </script> 

We can provide this as all one tag, but this format does several things. First, it keeps the consumer from accidentally passing on the script tag, which could potentially cause errors or problems in the user interface. Second, it keeps the information in a more data-centric format that allows the consumer a little more flexibility in utilizing it. For instance, the consumer may decide to go ahead and reference the script off of the service provider's server and add it inline to the content being delivered to the end user.

Of course, this is all helpful to the process, but validation must still be done by the applications involved. Just as with any enterprise Web application, providing client-side validation is for efficiency's sake to catch the majority of basic errors that can occur. These client-side rules can be turned off or bypassed, however, so you must have server-side validation to protect your application, whether you are the consumer or the Web service provider.