Creating an Atom service document

Create an Atom service document to inform clients about the collections that are available from your server. An Atom service document lists only Atom feeds that you want to make available as collections for editing; it does not include ordinary Atom feeds that are not available for editing.

1. If you want to define your Atom service document as an Atom configuration file, begin the document with the root element <cics:atomservice type="service">, and add the <app:service> element as a child element.

   <?xml version="1.0"?>
   <cics:atomservice type="service">
    <app:service>
    </app:service>
   </cics:atomservice>

   If you do not want to define the Atom service document as an Atom configuration file, use the <app:service> element as the root element, as follows:

   <?xml version="1.0"?>
   <app:service>
   </app:service>
   

2. Include the namespace declarations for the Atom XML namespace and the namespace for the Atom Publishing Protocol in the root element of the Atom service document; that is, either the <cics:atomservice> element or the <app:service> element.
   If you have used the <cics:atomservice> element as the root element, also include the namespace declaration for the CICS Atom XML namespace.
   For example:

   <?xml version="1.0"?>
   <cics:atomservice type="service"
         xmlns:cics="http://www.ibm.com/xmlns/prod/cics/atom/atomservice"
         xmlns:atom="http://www.w3.org/2005/Atom"
         xmlns:app="http://www.w3.org/2007/app">
    <app:service>
    </app:service>
   </cics:atomservice>

   With the <app:service> element as the root element, the declarations look like this:

   <?xml version="1.0"?>
   <app:service
         xmlns:atom="http://www.w3.org/2005/Atom"
         xmlns:app="http://www.w3.org/2007/app">
   </app:service>

3. Add at least one <app:workspace> element as a child element of the <app:service> element, and add an <atom:title> element to each workspace with a suitable title.
   <app:workspace> elements just group collections together in the service document, and the server and client do not have to take any actions relating to them. However, the Atom Publishing Protocol requires that you use at least one workspace, and that each workspace has a human-readable title.
   This example shows a single workspace that can contain all your collections:

   <?xml version="1.0"?>
   <cics:atomservice type="service"
         xmlns:cics="http://www.ibm.com/xmlns/prod/cics/atom/atomservice"
         xmlns:atom="http://www.w3.org/2005/Atom"
         xmlns:app="http://www.w3.org/2007/app">
    <app:service>
     <app:workspace>
        <atom:title>CICS Atom collections</atom:title>
     </app:workspace>
    </app:service>
   </cics:atomservice>

4. For each of your collections, add an <app:collection> element as a child element of the <app:workspace> element (or in a suitable <app:workspace> element if you have created more than one).
   Specify the following required items in each <app:collection> element:
   1. An href attribute of the <app:collection> element, stating the complete URL for the collection, with the complete path that you specified in the Atom configuration file for the collection.
      Web clients use this URL for GET requests to retrieve a list of the Atom entries in the collection. They also use this URL for POST requests to submit new Atom entries to the collection.
      You must ensure that this link is valid, and that you have set up all the items needed to support the collection, including a URIMAP resource definition and an ATOMSERVICE resource definition.
   2. An <atom:title> element as a child element, stating the title of the collection.
   For example:

   <app:workspace>
       <atom:title>CICS Atom collections</atom:title>
     <app:collection 
         href="http://www.example.com/customers/customercol.atom">
            <atom:title>Customer collection</atom:title>
     </app:collection>
   </app:workspace>
   

5. Optional: If you do not want clients to create new Atom entries in one or more of your collections, include an empty <app:accept> element as a child element of the <app:collection> element.
   For example:

     <app:collection 
         href="http://www.example.com/customers/customercol.atom">
            <atom:title>Customer collection</atom:title>
            <app:accept/>
     </app:collection>
   

   You must implement additional security measures to prevent clients from editing the collection. Clients should interpret an empty <app:accept> element to mean that they cannot create entries, but the presence of an empty <app:accept> element does not make CICS prevent a client from attempting to create an entry.

   If you want clients to create Atom entries, omit the <app:accept> element. Because CICS does not support media resources, do not use the <app:accept> element to specify any additional media types for entries. CICS rejects any client request to create an entry that is not an Atom entry document; that is, a document with the media type application/atom+xml, with or without the type=entry attribute. This media type is the default, so when you omit the <app:accept> element, clients should understand that they can create only Atom entry documents in this collection.

6. Optional: If you want to specify categories (which are optional) for the Atom entries in one or more of your collections, decide whether you want to provide the list of categories in the service document itself, or supply a reference to a separate category document.
   A separate category document is useful if you have a long list of categories, or if you want to reuse the same list of categories for different collections.
   The Atom Publishing Protocol permits you to use multiple <app:categories> elements in a service document, so you might choose, for example, to provide both a reference to a shared Atom category document and a list of categories specific to the collection.
   When you have made your decision, proceed as follows:
   1. To provide categories in the service document, add an <app:categories> element as a child element of the <app:collection> element, then add one or more <atom:category> elements as child elements of the <app:categories> element. Give each <atom:category> element a term attribute that specifies the name of the category.
      CICS does not support the optional scheme and label attributes, so do not use these attributes.
      For example:

        <app:collection 
            href="http://www.example.com/customers/customercol.atom">
               <atom:title>Customer collection</atom:title>
            <app:categories>
               <atom:category term="Customers" />
               <atom:category term="Actions" />
            </app:categories>
        </app:collection>
      

      The categories that you specify do not affect the way CICS behaves. CICS accepts client requests that specify a category that is not included in your list. For this reason, for a request where CICS handles the resource directly, do not use the fixed="yes" attribute in your <app:categories> element, which indicates that the server does not allow any other categories. When you omit the fixed attribute, a value of "no" is assumed. If you are using a service routine to make changes to the resource, you may code your service routine to reject client requests on the basis of categories, and indicate this in your <app:categories> element.
   2. To provide categories in a separate category document, follow the instructions in Creating an Atom category document to create a category document and the resource definitions that it requires. Then add an <app:categories> element as a child element of the <app:collection> element, and give it an href attribute specifying the URL that the client can use to retrieve your category document.
      For example:

        <app:collection 
            href="http://www.example.com/customers/customercol.atom">
               <atom:title>Customer collection</atom:title>
            <app:categories href="http://www.example.com/cat/customercol"/>
        </app:collection>
      

      You must not use any attributes or child elements in the <app:categories> element when you specify a reference to a category document.

<?xml version="1.0"?>
<cics:atomservice type="service"
      xmlns:cics="http://www.ibm.com/xmlns/prod/cics/atom/atomservice"
      xmlns:atom="http://www.w3.org/2005/Atom"
      xmlns:app="http://www.w3.org/2007/app">
 <app:service>
  <app:workspace>
    <atom:title>CICS Atom collections</atom:title>
   <app:collection 
      href="http://www.example.com/customers/customercol.atom">
         <atom:title>Customer collection</atom:title>
      <app:categories>
         <atom:category term="Customers" /> 
         <atom:category term="Actions" />
      </app:categories>
   </app:collection>
   <app:collection 
      href="http://www.example.com/sysadmin/messagecol.atom">
      <atom:title>Messages from the systems administrator</atom:title>
      <app:categories href="http://www.example.com/cat/messagecol"/>
   </app:collection>
  </app:workspace>
 </app:service>
</cics:atomservice>