URLs for Atom feeds from CICS

Atom feed documents, collections, and Atom entry documents within feeds or collections, contain URLs (Uniform Resource Locators) that web clients can use to interact with the documents. Each URL is provided in an <atom:link> element in the Atom document. An Atom document can have more than one <atom:link> element, and the rel attribute of the element, known as the link relation, specifies the purpose of the different URLs.

An Atom feed document or collection served by CICS® contains up to four types of URL:
  • A URL that locates the whole of the Atom feed or collection. This feed URL is provided in an <atom:link rel="self" > element that is a child element of the <atom:feed> element. A web client can use this URL to obtain an Atom feed document containing multiple entries from the Atom feed or collection.
  • Individual URLs to locate each Atom entry in the feed or collection. These entry URLs are provided in <atom:link rel="self" > elements that are child elements of the <atom:entry> element. A web client can use these URLs to retrieve single Atom entries from the feed or collection.
  • Editing URLs that web clients can use to make requests to edit a collection. These URLs are provided in <atom:link rel="edit" > elements. CICS provides one editing URL for the whole of a collection, as a child element of the <atom:feed> element in the collection document, and individual editing URLs for each Atom entry in a collection, as child elements of the <atom:entry> elements. CICS also provides <atom:link rel="self" > URLs for collections and Atom entries in collections.
  • Navigation URLs that web clients can use to retrieve partial lists of the Atom entries in an Atom feed or collection. These URLs are provided in <atom:link> elements with rel attributes of "first", "previous", "next", and "last". These URLs enable web clients to explore the whole of an Atom feed or collection without having to retrieve all the Atom entries at once. CICS provides an <atom:link rel="next"> element in Atom feed documents with a URL that web clients can use to retrieve the next window of Atom entries from the feed. In Atom documents that contain partial lists of entries from collections, CICS adds <atom:link> elements with rel attributes of "first", "previous", "next", and "last", to provide navigation to the other partial lists of Atom entries from the collection.

For an Atom feed, the URL for the whole feed is typically publicized on the Internet or a company's intranet. When a web client obtains an Atom feed document by using the feed URL, the Atom entries in the Atom feed document include their own individual URLs, and a web client can use these to retrieve single Atom entries.

For a collection, which contains Atom entries that can be edited, the service document that is available from the server provides the editing URL of each of the collections on the server. A web client can use one of these URLs to view the Atom entries in the collection and make requests to add further entries to it. The web client can use the editing URL for an individual Atom entry to make a request to update or delete the entry.

The Atom Syndication Format allows the use of Internationalized Resource Identifiers (IRIs), which permit Unicode characters and formats that are suitable for national languages other than English. You may use IRIs that include Unicode characters as the resource locators for Atom feeds from CICS, in place of an ordinary URL. In the RFCs for the Atom Syndication Format and the Atom Publishing Protocol, the resource locators for Atom feeds and Atom entries are referred to as IRIs. Internationalized Resource Identifiers (IRIs) explains IRIs and how you can use them for Atom feeds.

How Atom URLs are specified and resolved

In CICS, you use the <atom:link> child elements of the <atom:feed> and <atom:entry> elements in an Atom configuration file to specify a URL for the whole of the Atom feed or collection, and also a standard URL for the individual Atom entries. In the Atom configuration file you always specify <atom:link rel="self"> for these child elements, and when CICS sends out the Atom document, CICS adds an identical link in an <atom:link rel="edit" > element to collections and Atom entries in collections. You may omit the scheme and host components of the URL from the Atom configuration file, and specify only the path component. CICS adds the scheme and host components to the URLs when it returns the feed or entry document to the client.

You do not need to specify any of the <atom:link> elements for navigation URLs, with rel attributes of "first", "previous", "next", and "last", in your Atom configuration file. CICS creates these links for you.

The URLs that you specify for the whole feed and as a standard URL for the individual entries must have path components that begin in the same way. You specify this common part of the path component in the URIMAP resource definition that CICS uses to handle web client requests for the Atom feed, and use an asterisk to indicate that the rest of the path is to be used for path matching. The common part of the path component is what CICS uses to identify the Atom feed or collection, so it must be unique to this Atom feed or collection among all the Atom feeds or collections that you serve using a given host name.

When a web client makes a request using a URL that includes this common part of the path component, CICS finds the matching URIMAP resource definition, and uses a number of other resources to map the request URL to the data for the Atom feed. Figure 1 shows this process for a feed URL:

Figure 1. Request URLs for Atom feeds
The diagram shows a request URL www.example.com/atom/cicsfile/filea, which maps to a URIMAP resource that specifies PATH(atom/cicsfile/*) and USAGE(ATOM). The URIMAP names an ATOMSERVICE resource. The ATOMSERVICE resource locates an Atom configuration file that contains the tag <atom:link rel=“self” href=“/atom/cicsfile/filea”>, which is the URL for the Atom feed.
  • To handle incoming requests from web clients, you create a URIMAP resource definition that specifies the part of the path component that is common to the feed and entry URLs. In this example, the common part of the path component is atom/cicsfile/. When a web client makes a request using the URLs that you have defined for an Atom feed or collection or for an Atom entry, CICS finds the URIMAP resource that matches the common part of the path component. In this example, the web client requests the Atom feed using the feed URL www.example.com/atom/cicsfile/filea.
  • The URIMAP resource specifies an ATOMSERVICE resource that names the Atom configuration file, XML binding (XSDBIND file), and CICS resource that provide the Atom feed. The example ATOMSERVICE resource names the FILEA file as the resource that holds the data for the Atom entries.
  • CICS uses the ATOMSERVICE resource to locate the Atom configuration file, and compares the path component of the inbound URL used by the web client to the URLs specified in all the <atom:link> elements in the Atom configuration file. When CICS finds a URL in an <atom:link> element that has a matching path component, it carries out the appropriate action, either returning the Atom feed or entry document or implementing the edit request. In this example, the request URL used by the web client matches the URL specified for the Atom feed in the Atom configuration file, so CICS must return an Atom feed document.
  • The Atom configuration file, like the ATOMSERVICE resource, names the FILEA file as the resource that holds the data for the Atom entries. As explained in Data processing for Atom feeds from CICS, CICS might operate directly to extract the data from the file or temporary storage queue that contains the data for the Atom entries, or pass the request on to a service routine.

In Figure 1, the path for the URL for the whole Atom feed, as specified in the <atom:link> child element of the <atom:feed> element in the Atom configuration file, is /atom/cicsfile/filea. The <atom:entry> element in the Atom configuration file also has an <atom:link> child element, which contains the path /atom/cicsfile/entry. This is a standard path for Atom entries. The standard path for Atom entries begins with the common part of the path component, atom/cicsfile/. The remainder of the standard path for Atom entries must be different from the path for the Atom feed that is specified in the <atom:link> child element of the <atom:feed> element. CICS uses this part of the path for path matching within the Atom configuration file, to determine whether an Atom feed document or an Atom entry document is required.

Figure 2 shows how CICS handles a request from a web client for a single Atom entry, and identifies the correct Atom entry:
Figure 2. Request URLs for Atom entries
The diagram shows a request URL www.example.com/atom/cicsfile/entry/23, which maps to a URIMAP resource that specifies PATH(atom/cicsfile/*) and USAGE(ATOM). The URIMAP names an ATOMSERVICE resource. The ATOMSERVICE resource locates an Atom configuration file that contains the tag <atom:link rel=“self” href=“/atom/cicsfile/entry”>, which is a prototype URL for Atom entries. The number 23 on the end of the request URL locates record number 23 in the FILEA file.
  • The web client requests a single Atom entry using the URL www.example.com/atom/cicsfile/entry/23. The web client obtained this URL from the <atom:link> child element for the Atom entry, which the web client originally received as part of an Atom feed document.
  • The Atom entry URL contains the common part of the path component for the Atom feed, atom/cicsfile/, so it is handled by the same URIMAP and ATOMSERVICE resources as the feed URL. In this example, the request URL used by the web client matches the standard path specified for Atom entries in the Atom configuration file, so CICS must return an Atom entry document.
  • CICS identifies the Atom entry to return to the web client by examining the remainder of the request URL that follows the standard path. In this example, the request URL contains the number "23". This is the selector value for the entry. The selector value is an identifier, typically a number, that identifies the record in a file, temporary storage queue, or other resource that contains the data for the Atom entry. In this example, the selector value chosen for the Atom entries was the record number. When you choose a selector value, you must make sure that the URL for the whole Atom feed and the standard path for Atom entries will still be different when the selector value is appended to them. Selector value for Atom entries explains in more detail how selector values are chosen and used.

CICS also uses the selector value to build navigation links to partial lists of entries from the Atom feed or collection, in the <atom:link> elements with rel attributes of "first", "previous", "next", and "last". CICS builds these navigation links by taking the path that you specified for the whole of the Atom feed or collection, and appending the selector value for the Atom entry that appears at the beginning of the partial list. CICS uses this information together with the window setting specified for the Atom feed or collection to return a partial list to the web client. In the example Atom feed used here, for a partial list of entries that begins with the Atom entry with the selector value "9", CICS creates the link www.example.com/atom/cicsfile/filea/9.

These examples show the selector value being appended to the URLs in the default format, known as the "segment" format, where the selector value is placed as the final segment of the path component. As an alternative, you can choose a URL style that is compatible with applications developed using the CA8K SupportPac, where the selector value for the Atom entry is placed in a query string. You can specify this alternative "query" format using the <cics:selector> element in the Atom configuration file. If <cics:selector style="query"/> is specified for the example Atom feed used here, CICS creates the links for individual Atom entries in the format www.example.com/atom/cicsfile/entry?s=23. The same format is used for the navigation links.