Balisage Paper: XQuery Design Patterns

Description

Applying the Chain of Responsibility to our use case results in making a separation between the code that is responsible for sending the request and each of the functions configuring the request (i.e. setup the request for AtomPub and putting authentication information in the request). In order to do so, we identify the following participants (also see Fig. 1):

Spreading the functionality among the three participants allows us to easily rewrite the client, for example to use a different authentication strategy. In particular, we avoid that different library modules "know about" each other, i.e. they are not imported into each other.

1

Structure of the Chain of Responsibility.

Implementation

In this section, we describe one possible implementation of our use case by applying the Chain of Responsibility pattern. ^[3]

First, we start with a description of the implementation of the client which is implemented in a function called local:post-entry. After this, we describe the two functions atompub-client:post and http-auth:basic. Each of these functions takes as first parameter the request item which is prepared in the body of each function.

(:
 : This function initializes the HTTP request, passes it to three
 : chained functions (atompub-client:post, http-auth:basic, and 
 : httpclient:send-request), and returns the result of the last 
 : invoked function.
 :)
declare sequential function local:post-entry() as item()*
{
  (: Initialize the request :)
  declare $request  := validate { 
      <http:request href="http://atompubtest.my28msec.com/blog/feed"
                    method="GET" />
  };
  (: Update the request according to the AtomPub protocol
   : $local:entry is the Atom entry to be sent 
   :)
  atompub-client:post($request, $local:entry);
  (: Basic HTTP Authentication. :)
  http-auth:basic($request, "Username", "Password");
  (: Finally, send the request to the AtomPub server :)
  http-client:send-request($request);
};
        

In the code snippet above, the HTTP request element ($request) is declared and initialized containing the URL of the AtomPub server. This element is passed along the chain of functions atompub-client:post and http-auth:basic ending up in a call to the http-client:send-request() function. The latter function takes over the responsibility of executing the request.

(:
 : AtomPub POST handler.
 : Update the HTTP request according to the
 : AtomPub protocol specification.
 :)
declare updating function atompub-client:post(
    $request as schema-element(http:request),
    $entry   as schema-element(atom:entry))
{
    replace value of node $request/@method with "POST",
    
    insert node <http:body media-type="application/xml"
                           method="xml">{$entry}</http:body>
    as last into $request
};          
          

The function atompub-client:post() "massages" the request item (using XQuery update) according to the AtomPub specification. Specifically, this function makes sure that the HTTP request method is set to POST. Moreover, it configures the body of the HTTP request to contain the entry to be published.

After that, the http-auth:basic() function adds username and password attributes to the request and sets the authentication method to basic.

(:
 : Basic HTTP Auth handler.
 : Update the HTTP request according to the
 : basic HTTP authentication specification.
 :)
declare updating function http-auth:basic(
    $request  as schema-element(http:request),
    $username as xs:string,
    $password as xs:string)
{
  insert node (attribute username    { $username },
               attribute password    { $password },
               attribute auth-method { "basic" })
  into $request
};          
         

Implementation Considerations

In the implementation presented in the last section, we made some decisions in order to make the essence of the paper easier to understand and improve the readability of the code. Neither are these decisions mandatory for implementing Chain of Responsibility nor might they be optimal. Therefore this pattern can be implemented in XQuery 1.0. In this section, we discuss some alternative implementation aspects.

Conclusion

The Chain of Responsibility helped us to improve the flexibility and reusability of the modules involved to implement Use Case 1. As a result, we gained the following:

Use Chain of Responsibility if

Description

Since the goal of Translator is to bring the XSLT programming paradigm into XQuery, the participants involved in this pattern have the same names and also have a similar semantics as their complements in XSLT. The participants involved are the following:

Figure 2 shows the dependencies between the participants for Translator applied to the GeoRSS example describe in the previous section. The figure illustrates that (1) only the Atom templates (apply and match for Atom feeds and entries) need to know the Atom schema, (2) the template responsible for transforming GeoRSS only knows the GeoRSS schema, and (3) the transform function orchestrates the transformation process by invoking the function items of the templates.

2

Structure of Translator.

Figure 3 depicts this orchestration of the translation process. The client invokes the transform function passing the XDM instance and the templates as parameters. For each template, the transform function first executes the match function passing the current XDM instance as parameter. If the result of the invocation of match is true, then the apply function is invoked on this instance. Please note that the apply function itself may repeatably invoke the transform function to further transform nested structures.

3

Collaborations in Translator.

Implementation

In this section, we describe the implementation of Translator for the GeoRSS-to-HTML transformation (see above).^[4]. We start with a presentation of the transform function which receives the XDM instance to transform (i.e. the Atom feed) and the transformation templates as parameters.

declare function converter:transform(
  $i as item()*,
  $templates as function(*)+) as item()*
{
  for $tpl in $templates
  let $template := $tpl()
  let $match    := $template[1]
  let $apply    := $template[2]
  return
    if($match($i)) then
      $apply($i, converter:transform#2, $templates)
    else()
};        
        

This function invokes the apply and match functions for all templates. The example application contains templates for Atom feeds, Atom entries, and GeoRSS points. For instance, it contains an xhtml-template module which contains templates to transform Atom feeds and entries into XHTML. Moreover, it contains a module to match and apply GeoRSS points.^[5] For example, the Atom module contains two templates each consisting of a match and an apply function:

The functions match-feed and match-entry are respectively checking if the XDM instance is an Atom feed or entry.

 declare function html-templates:match-feed($item) as xs:boolean
{
    $item instance of schema-element(atom:feed)
};       
        

 declare function html-templates:match-entry($item) as xs:boolean
{
    $item instance of schema-element(atom:entry)
};
        

Both of the match functions are associated to apply functions, namely apply-feed and apply-entry. Each of the apply functions shown below is invoking the transform function. More specifically, in apply-feed, the transform function is invoked for each Atom entry in the feed. In apply-entry, the transform function is invoked for all children of an entry. If one of the children is contained in the GeoRSS namespace, it will be transformed by a matching template.

declare function html-templates:apply-feed(
    $feed as schema-element(atom:feed),
    $transform as (function(item()*, function(*)+) as item()*),
    $templates as function(*)+)
{
    <html xmlns="http://www.w3.org/1999/xhtml">
        <h1>{$feed/atom:title/text()}</h1>
        <div id="entries">{
         for $entry in $feed/atom:entry
         return $transform($entry, $templates)
        }</div>
    </html>
};  

declare function html-templates:apply-entry(
    $entry as schema-element(atom:entry),
    $transform as (function(item()*, function(*)+) as item()*),
    $templates as function(*)+)
{
    <div class="atom:content"
         xmlns="http://www.w3.org/1999/xhtml">
      <h2>{$entry/atom:title/text()}</h2>
      <div class="atom:content">
      {$entry/atom:content/text()}
      </div>
      {for $child in $entry/*
       return $transform($child, $templates)}
    </div>
};

Finally, the client invokes the transform function for the first time, passing as first argument an instance of an Atom feed to be converted and as second argument the templates as parameters.

(: Display the Atom feed :)
let $feed := local:get-feed()
return algo:transform($feed, tohtml:get-templates());      
    

Implementation Considerations

In the previous section, we have introduce one possible implementation of Translator. In this section, we consider some alternative implementation aspects.

Conclusion

By implementing Use Case 2 (Sec. 2) using Translator, we have improved the application on the following perspectives:

Description

In order to implement our use case with the Strategy Pattern, we have to decouple the AtomPub operations from the storage operations. Therefore, we call the AtomPub operations passing a function item encapsulating the storage Strategy as parameter. Strategy defines the following participants (cf. Gamma1994):

ContextFunction and ConcreteStrategy interact to implement the Strategy chosen by the server. A ContextFunction may pass all data required to the ConcreteStrategy at runtime. The client creates and passes a ConcreteStrategy to a ContextFunction.

4

Structure of the Strategy Pattern.

In Figure 4, the atompub:post function is responsible for creating a new Atom entry. The create-strategy argument is a function item that encapsulates the functionality to store an entry. Therefore, it represents a concrete Strategy that stores the entry, for example in a collection. Different concrete storage strategies are implemented within different modules that have no dependencies with the AtomPub server module. For instance, atompub:post could use one of these strategies:

Whenever the AtomPub server has to retrieve or create data, it forwards the responsibility to the concrete Strategy which is passed as a function argument.

Implementation

Within this section, we describe one possible implementation of the AtomPub server use case using the Strategy pattern ^[6].

First, we show how a ConcreteStrategy is chosen and used within the Context, i.e. the main module; in our example application we use the concrete file system storage Strategy. After that, we present the usage of the ConcreteStrategy within the atompub:post ContextFunction. Finally, we will present the concrete implementation of the create algorithm, i.e. a chosen ConcreteStrategy implemented in the store:create function.

The code listing below shows the main server module which handles an Atom entry posting from a client. By importing the file system store (not shown in the code snippet below) the main module chooses the concrete store strategy. It then calls atompub:post passing store:create as the chosen storage strategy.

(: 
 : Post the entry, the result is the URI of the entry 
 : using store:create#2 as the storage strategy
 :)
let $feed-uri  := "http://www.example.org/blog"
let $entry-uri := atompub:post($feed-uri, $local:entry, store:create#2)
(: Get the newly created entry :)
return store:retrieve-entry($entry-uri)          

The ContextFunction atompub:post shown below is processing an Atom entry posted by a client. It takes three parameters: the feed uri, the entry to be aggregated, and the storage strategy. First, the entry is processed. Then it is passed as parameter to the invoked strategy function item.

(: Post an entry :)
declare sequential function atompub:post(
    $feed-uri as xs:string,
    $entry as schema-element(atom:entry),
    $create-strategy 
as (function(xs:string, schema-element(atom:entry)) as item()*)
) as xs:string
{
    (: Prepare the entry :)
    declare $id := util:uuid();
    declare $entry-uri := concat($feed-uri, "/", $id);
    insert nodes (<atom:id>{$id}</atom:id>,
                  <atom:link href="{$entry-uri}" rel="self" />)
    into $entry;
    (: Use strategy to store the entry :)
    $create-strategy($feed-uri, $entry);
    (: Return the entry URI :)
    $entry-uri;
};          
        

The common interface of the create-strategy algorithm to create an entry is implicitly defined as function(xs:string, schema-element(atom:entry)). Within XQuery there is no explicit mechanism to define an interface in the manner of an object oriented language like Java. Therefore, one implicit way to define the common interface for the actual Strategy is by definition of the function item parameter within the signature of the ContextFunction.

declare sequential function store:create(
    $feed-uri as xs:string,
    $entry as schema-element(atom:entry))
{
  declare $filename  := store:get-filename($feed-uri);
  declare $meta-feed := validate { 
    fs:read-xml($filename)/atom:feed
  };
  declare $entry-uri := 
    $entry/atom:link[string(@rel) eq "self"]/@href;
  (: Create the entry in the file system :)
  fs:write(store:get-filename($entry-uri), $entry, ());
  (: Update the feed metadata :)
  insert node <atom:link href="{$entry-uri}" rel="entry" />
  as first into $meta-feed;
  fs:write($filename, $meta-feed, ());
};          
          

Implementation Considerations

When implementing the Strategy pattern, the Strategy may be optional [Gamma1994]. If no Strategy is provided, we execute the default behavior of the function.

The Strategy implemented in our use case has side effects: it stores data in the file system. Therefore the use of XQuery Scripting Extension depends on the algorithm implementation that needs to be achieved, not on the Strategy pattern itself.

Conclusion

By adapting the Strategy pattern in our example application we gained the following benefits (cf. Gamma1994):

We encourage usage of the Strategy pattern when

Description

When applying the Observer pattern to our use case, we have decoupled collaborative modules by introducing a subscription mechanism for functions to be invoked on particular events in the application.

The Observer pattern defines the following participants (cf. Gamma1994):

Observers are attached to the Subject. If a particular event occurs, the subject invokes all its observers and provides each of them with data about the event that triggered the invocation. A Subject can have many Observers, each Observer implementing a different functionality.

Subjects and Observers are loosely coupled: they can vary independently [Gamma1994]. Consider our use case, adding/removing Observers doesn't affect neither the AtomPub server module nor the Twitter Observer function. Both modules (AtomPub and Twitter) can operate without the other. The Observer pattern is enables collaborations between these two decoupled modules.

Implementation

In this section, we discuss the implementation of the Observer pattern in our application ^[7]. Figure 4 describes the structure of our Observer implementation. The implementation of the Observer pattern in our application involves the AtomPub server module (the Subject) and the tweet-entry function (the Observer).

4

Structure of Observer.

The on-post function is responsible for attaching new observers to the AtomPub server module (the Subject). The AtomPub server is keeping track of all its observers with the on-post module variable.

(: Hold the observer references :)
declare variable $atompub:on-post
  as (function(schema-element(atom:entry)) as item()*)* := ();

(: Add an observer to the post request :)
declare sequential function atompub:on-post(
  $o as (function(schema-element(atom:entry)) as item()*))
{
    set $atompub:on-post := ($atompub:on-post, $o)
};            
          

In order for the subject to be able to invoke an Observer, all observers must have the same function signature. For instance, in the AtomPub server module, each observer must be a subtype of function(schema-element(atom:entry)) as item()*. The single parameter of the observer, (schema-element(atom:entry)) is an instance of the Atom entry that has been created on the server.

The tweet-entry function is the Observer we will use in our use case: it will be executed for each new entry created on the server. It takes an Atom entry as parameter and sends a message on Twitter with the following format: entry title, tiny url of the entry. The function signature is compatible with the observer signature defined in the AtomPub server module (function(schema-element(atom:entry)) as item()*).

(: The tweet will be formatted as following: Title + tiny url :)
declare function twitter:tweet-entry(
  $entry as schema-element(atom:entry))
{ 
  (: Get the title :)
  let $title := $entry/atom:title/text()
  (: Create a tiny link :)
  let $uri := twitter:get-tiny-url(
    string($entry/atom:link[@rel = "self"]/@href)
  )
  (: Send the status on twitter :)
  return twitter:tweet(concat($title, ": ", $uri))
};          
        

The Client registers the tweet-entry function as an Observer of the AtomPub server module.

(: Register the Twitter observer :)
atompub:on-post(twitter:tweet-entry#1);        
      

When a new Atom entry is added to the server, each Observer is notified and receives the entry as parameter.

(: Notify observers :)
for $o in $atompub:on-post
return $o($entry);         
          

Implementation Considerations

In the previous section, we introduced an implementation of the observer pattern. In this section, we discuss how this implementation can vary:

Conclusion

By using Observer to implement Use Case 4, the application has improved in the following perspectives:

In conclusion, use the Observer pattern if you want to: