Dispatching requests and responses

One reason to use WebSnap for your Web server application development is that WebSnap components automatically handle HTML requests and responses. Instead of writing event handlers for common page transfer chores, you can focus your efforts on your business logic and server design. Still, it can be helpful to understand how WebSnap applications handle HTML requests and responses. This section gives you an overview of that process.

Before handling any requests, the Web application module initializes the Web context object (of type TWebContext). The Web context object, which is accessed by calling the global WebContext function, provides global access to variables used by components servicing the request. For example, the Web context contains the TWebRequest and TWebResponse objects to represent the HTTP request message and the response that should be returned.

Dispatcher components

The dispatcher components in the Web application module control the flow of the application. The dispatchers determine how to handle certain types of HTTP request messages by examining the HTTP request.

The adapter dispatcher component (TAdapterDispatcher) looks for a content field, or a query field, that identifies an adapter action component or an adapter image field component. If the adapter dispatcher finds a component, it passes control to that component.

The Web dispatcher component (TWebDispatcher) maintains a collection of action items (of type TWebActionItem) that know how to handle certain types of HTTP request messages. The Web dispatcher looks for an action item that matches the request. If it finds one, it passes control to that action item. The Web dispatcher also looks for auto-dispatching components that can handle the request.

The page dispatcher component (TPageDispatcher) examines the PathInfo property of the TWebRequest object, looking for the name of a registered Web page module. If the dispatcher finds a Web page module name, it passes control to that module.

Adapter dispatcher operation

The adapter dispatcher component (TAdapterDispatcher) automatically handles HTML form submissions, and requests for dynamic images, by calling adapter action and field components.

Using adapter components to generate content

For WebSnap applications to automatically execute adapter actions and retrieve dynamic images from adapter fields, the HTML content must be properly constructed. If the HTML content is not properly constructed, the resulting HTTP request will not contain the information that the adapter dispatcher needs to call adapter action and field components.

To reduce errors in constructing the HTML page, adapter components indicate the names and values of HTML elements. Adapter components have methods that retrieve the names and values of hidden fields that must appear on an HTML form designed to update adapter fields. Typically, page producers use server-side scripting to retrieve names and values from adapter components and then uses this information to generate HTML. For example, the following script constructs an <IMG> element that references the field called Graphic from Adapterl:

<img src="<%=Adapter1.Graphic.Image.AsHREF%>" alt="<%=Adapter1.Graphic.DisplayText%>">

When the Web application evaluates the script, the HTML src attribute will contain the information necessary to identify the field and any parameters that the field component needs to retrieve the image. The resulting HTML might look like this:

<img src="?_lSpecies No=90090&__id=DM.Adapter1.Graphic" alt="(GRAPHIC)">

When the browser sends an HTTP request to retrieve this image to the Web application, the adapter dispatcher will be able to determine that the Graphic field of Adapterl, in the module DM, should be called with "Species No=90090" as a parameter. The adapter dispatcher will call the Graphic field to write an appropriate HTTP response.

The following script constructs an <A> element referencing the EditRow action of Adapter1 and creates a hyperlink to a page called Details:

<a href="<%=Adapter1.EditRow.LinkToPage("Details", Page.Name).AsHREF%>">Edit...</a>

The resulting HTML might look like this:

<a href="?&_lSpecies No=90310&__sp=Edit&__fp=Grid&__id=DM.Adapter1.EditRow">Edit...</a>

The end user clicks this hyperlink, and the browser sends an HTTP request. The adapter dispatcher can determine that the EditRow action of Adapterl, in the module DM, should be called with the parameter Species No=903010. The adapter dispatcher also displays the Edit page if the action executes successfully, and displays the Grid page if action execution fails. It then calls the EditRow action to locate the row to be edited, and the page named Edit is called to generate an HTTP response. Figure 35.5 shows how adapter components are used to generate content.

Figure 35.5 Generating content flow

Server

Figure 35.5 Generating content flow

Server

Receiving adapter requests and generating responses

When the adapter dispatcher receives a client request, the adapter dispatcher creates adapter request and adapter response objects to hold information about that HTTP request. The adapter request and adapter response objects are stored in the Web context to allow access during the processing of the request.

The adapter dispatcher creates two types of adapter request objects: action and image. It creates the action request object when executing an adapter action. It creates the image request object when retrieving an image from an adapter field.

The adapter response object is used by the adapter component to indicate the response to an adapter action or adapter image request. There are two types of adapter response objects, action and image.

Action requests

Action request objects are responsible for breaking the HTTP request down into information needed to execute an adapter action. The types of information needed for executing an adapter action may include the following request information:

Table 35.5 Request information found in action requests

Request informaton Description

Component name Adapter mode

Success page Failure page

Action request parameters

Adapter field values

Record keys

Identifies the adapter action component.

Defines a mode. For example, TDataSetAdapter supports Edit, Insert, and Browse modes. An adapter action may execute differently depending on the mode.

Identifies the page displayed after successful execution of the action.

Identifies the page displayed if an error occurs during execution of the action.

Identifies the parameters need by the adapter action. For example, the TDataSetAdapter Apply action will include the key values identifying the record to be updated.

Specifies values for the adapter fields passed in the HTTP request when an HTML form is submitted. A field value can include new values entered by the end user, the original values of the adapter field, and uploaded files.

Specifies keys that uniquely identify each record.

Generating action responses

Action response objects generate an HTTP response on behalf of an adapter action component. The adapter action indicates the type of response by setting properties within the object, or by calling methods in the action response object. The properties include:

  • RedirectOptions—The redirect options indicate whether to perform an HTTP redirect instead of returning HTML content.
  • ExecutionStatus—Setting the status to success causes the default action response to be the content of the success page identified in the Action Request.

The action response methods include:

  • RespondWithPage —The adapter action calls this method when a particular Web page module should generate the response.
  • RespondWithComponent—The adapter action calls this method when the response should come from the Web page module containing this component.
  • RespondWithURL—The adapter action calls this method when the response is a redirect to a specified URL.

When responding with a page, the action response object attempts to use the page dispatcher to generate page content. If it does not find the page dispatcher, it calls the

Web page module directly.

Figure 35.8 illustrates how action request and action response objects handle a request.

Figure 35.6 Action request and response

WebSnap Application

Figure 35.6 Action request and response

Web Application Module

Web

Adapter

Action

Adapter

Request

Dispatcher

Request

Action

>

1

Web

Page

Action

Response

Dispatcher

Image request

The image request object is responsible for breaking the HTTP request down into the information required by the adapter image field to generate an image. The types of information represented by the Image Request include:

  • Component name - Identifies the adapter field component.
  • Image request parameters - Identifies the parameters needed by the adapter image. For example, the TDataSetAdapterImageField object needs key values to identify the record that contains the image.

Image response

The image response object contains the TWebResponse object. Adapter fields respond to an adapter request by writing an image to the Web response object.

Figure 35.7 illustrates how adapter image fields respond to a request.

Figure 35.7 Image response to a request

Figure 35.7 Image response to a request

Dispatching action items

When responding to a request, the Web dispatcher ( TWebDispatcher) searches through its list of action items for one that:

  • matches the Pathlnfo portion of the target URL's request message, and
  • can provide the service specified as the method of the request message.

It accomplishes this by comparing the PathInfo and MethodType properties of the TWebRequest object with the properties of the same name on the action item.

When the dispatcher finds the appropriate action item, it causes that action item to fire. When the action item fires, it does one of the following:

  • Fills in the response content and sends the response, or signals that the request has been completely handled.
  • Adds to the response, and then allows other action items to complete the job.
  • Defers the request to other action items.

After the dispatcher has checked all of its action items, if the message was not handled correctly, the dispatcher checks for specially registered auto-dispatching components that do not use action items. (These components are specific to multi-tiered database applications.) If the request message is still not fully handled, the dispatcher calls the default action item. The default action item does not need to match either the target URL or the method of the request.

Page dispatcher operation

When the page dispatcher receives a client request, it determines the page name by checking the Pathlnfo portion of the target URL's request message. If the Pathlnfo portion is not blank, the page dispatcher uses the ending word of Pathlnfo as the page name. If the Pathlnfo portion is blank, the page dispatcher tries to determine a default page name.

If the page dispatcher's DefaultPage property contains a page name, the page dispatcher uses this name as the default page name. If the DefaultPage property is blank and the Web application module is a page module, the page dispatcher uses the name of the Web application module as the default page name.

If the page name is not blank, the page dispatcher searches for a Web page module with a matching name. If it finds a Web page module, it calls that module to generate a response. If the page name is blank, or if the page dispatcher does not find a Web page module, the page dispatcher raises an exception.

Figure 35.8 shows how the page dispatcher responds to a request.

Figure 35.8 Dispatching a page

WebSnap Application

Server

Figure 35.8 Dispatching a page

WebSnap Application

Server

Was this article helpful?

+2 0

Responses

Post a comment