Online Library Example

This is an extended version of the example presented in BeepBeep's quick tour.

Consider a library which makes its catalog available online through a web service interface.

XML messages

The library allows its users to do the following:

1. Login/logout. This is done by sending a login message with a user login name xyz (we omit the password for the needs of the example):

<message>
  <action>login</action>
  <loginName>xyz</loginName>
</message>

The library can then send a confirmation:

<message>
  <action>loginConfirmation</action>
  <status>normal</status>
</message>

Alternatively, if the user has been a bad client, the library might kick him out for a week. During that week, access to the library for that client is restricted to catalog browsing and book return; no books can be borrowed. In such a case the status element contains the value restricted.

The user can logout at any time by sending a logout message:

<message>
  <action>logout</action>
</message>

2. Get the catalog. Querying the library catalog is done by sending a query message:

<message>
  <action>query</action>
  <author>Latrimoville</author>
  <title>Trout Fishing Secrets</title>
  <year>1991</year>
  <year-range>
    <begin>1989</begin>
    <end>1992</end>
  </year-range>
</message>

The message contains one or more fields indicating the terms of search. It can have multiple authors, but at most one title. The element year-range must contain begin and end; to avoid sending too many query results, the time span to search cannot be greater than ten years. Moreover, if a year range is specified, a year cannot be specified, and vice-versa (therefore the above message should not be sent).

The library returns a list of results:

<message>
  <action>queryResult</action>
  <books>
    <book>
      <author>T. Latrimoville</author>
      <title>Trout Fishing Secrets</title>
      <year>1989</year>
      <reference>BN 304.2 A68</reference>
      <status>available</status>
    </book>
    ...
  </books>
</message>

In the case a book is already taken, the status element takes the value unavailable.

3. Borrow/renew/return books. Borrowing, renewing and returning books all work the same way. For example, to borrow a list of books:

<message>
  <action>borrow</action>
  <books>
    <book>
      <reference>BN 304.2 A68</reference>
    </book>
    ...
  </books>
</message>

As many books as desired can be put in the list books. The library sends a confirmation:

<message>
  <action>borrowConfirmation</action>
  <books>
    <book>
      <reference>BN 304.2 A68</reference>
    </book>
    ...
  </books>
</message>

The confirmation gives the list of books that have been borrowed. This list is not necessarily identical as the one sent in the borrowing message. There cannot be more books, but there can be less if the client exceeded his quota and not all books could be borrowed. In that event, the client must not send any further borrow messages.

The dialog for renewal and return of books is similar, with message names of renew/renewConfirmation and return/returnConfirmation, respectively. All return operations must precede any borrow operations.

Clients can renew a book only once. They must then return the book and wait at least one day before borrowing the book again.

Service interface contract

The previous description of the library service, although written in plain English, is full of explicit and implicit constraints. Here is a list:

  1. If a loginConfirmation has a status of restricted, no borrow message can be sent during the whole transaction.
  2. A query message has at most one title.
  3. A query message has and at most one of year and year-range.
  4. A query with a year-range has a difference between end and begin of at least 1 and at most 10 years.
  5. If a borrowConfirmation does not list all books from the previous borrow message, no future borrow message can be sent.
  6. A borrowConfirmation should be received from the library immediately following a borrow message, and not in any other event. The same applies for the return and renew operations.
  7. All return operations must precede any borrow operations.
  8. A book that appears in a return message cannot appear in a borrow message in the same session.

Main menu

SourceForge.net Logo