Организация контента с помощью категорий Atom

Николас Чейз

Допустимые категории

Если вы решаете добавить категории к записям Atom, рассмотрите, какие из них вам доступны. Это можно узнать из сервисного документа Atom, который определяет существующие для определенной коллекции категории. Рассмотрим, например, сервисный документ по умолчанию для сервера Blogapps (смотри Листинг 1).

Листинг 1. Сервисный документ

                
<?xml version="1.0" encoding="UTF-8"?>
<app:service xmlns:app="http://purl.org/atom/app#" 
                     xmlns:atom="http://www.w3.org/2005/atom">
  <app:workspace>
    <atom:title>AdminBlog</atom:title>
    <app:collection 
         href="http://localhost:8080/roller/app/adminblog/entries">
      <atom:title>Weblog Entries</atom:title>
      <app:categories app:fixed="yes" 
              app:scheme="http://localhost:8080/roller/adminblog/">
        <atom:category atom:term="/General" atom:label="General" />
        <atom:category atom:term="/Status" atom:label="Status" />
        <atom:category atom:term="/Java" atom:label="Java" />
        <atom:category atom:term="/Music" atom:label="Music" />
        <atom:category atom:term="/Politics" atom:label="Politics" />
        <atom:category atom:term="/Music" atom:label="Music" />
      </app:categories>
      <app:accept>entry</app:accept>
    </app:collection>
    <app:collection 
          href="http://localhost:8080/roller/app/adminblog/resources">
      <atom:title>Media Files</atom:title>
      <app:accept>image/*</app:accept>
    </app:collection>
  </app:workspace>
  <app:workspace>
    <atom:title>main</atom:title>
    <app:collection 
             href="http://localhost:8080/roller/app/main/entries">
      <atom:title>Weblog Entries</atom:title>
      <app:categories app:fixed="yes" 
                    app:scheme="http://localhost:8080/roller/main/">
        <atom:category atom:term="/General" atom:label="General" />
        <atom:category atom:term="/Status" atom:label="Status" />
        <atom:category atom:term="/Java" atom:label="Java" />
        <atom:category atom:term="/Music" atom:label="Music" />
        <atom:category atom:term="/Politics" atom:label="Politics" />
      </app:categories>
      <app:accept>entry</app:accept>
    </app:collection>
    <app:collection 
               href="http://localhost:8080/roller/app/main/resources">
      <atom:title>Media Files</atom:title>
      <app:accept>image/*</app:accept>
    </app:collection>
  </app:workspace>
</app:service>

В этом случае в обеих коллекциях - adminblog и main - определены наборы категорий, однако на самом деле в этих данных гораздо больше информации, чем может показаться на первый взгляд.

Во-первых, обратите внимание на то, что у элементов category есть два важных атрибута. Атрибут term является фактическим представлением категории. Обратите внимание, что в этом случае каждый термин начинается с косой черты (/). Спецификация формата синдикации Atom не оговаривает вопрос формы представления термина, поэтому ничто не мешает вам создать иерархическую структуру категорий.

Вторым важным атрибутом является label, который представляет удобочитаемую версию категории.

На первый взгляд, оба набора категорий содержат одни и те же записи, но это не так. Если вы обратите внимание на элементы categories, вы заметите, что у них указывается атрибут схемы. Можно сказать, что схема категории предоставляет способ классификации ваших категорий. Например категория General в коллекции adminblog может обозначать нечто совершенно иное, нежели категория General коллекции main.

Вы можете даже совмещать схемы в одной коллекции, добавляя элемент scheme к конкретным элементам category.

Использование категорий

Добавление категорий к контенту - это просто добавление к вашей записи элемента category. Например, вы добавляете на сервер новую запись (см. Листинг 2).

Листинг 2. Добавление категории

                
POST /roller/app/main/entries HTTP/1.1
Host: localhost
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/atom+xml
Content-Length: 760

<entry xmlns="http://www.w3.org/2005/Atom">
    <title>Blogapps supports Atom (Java)</title>
    <updated>2007-12-13T12:30:02Z</updated>
    <summary>The spec's not actually out yet, but fortunately, you 
can still use it.</summary>
    <published>2007-05-25T08:29:29-04:00</published>
    <category term="Java" />
    <author>
      <name>Nick Chase</name>
      <uri>http://www.chaosmagnet.com</uri>
      <email>atomexample@nicholaschase.com</email>
    </author>
    <content type="xhtml" xml:lang="en"
           xml:base="http://diveintomark.org/">
      <div xmlns="http://www.w3.org/1999/xhtml">
         <p><i>The Blogapps server supports the upcoming Atom spec, 
so if you install it ...</i></p>
      </div>
    </content>
</entry>

Вы указали типовую категорию Java, поэтому результат покажет, что запись была добавлена к ней (смотри Листинг 3).

Листинг 3. Ответ

                
HTTP/1.1 201 Created
Server: Apache-Coyote/1.1
Set-Cookie: JSESSIONID=7818CFD9D1A9A53F5EA3B0A203ABBBCD; Path=/roller
Location: http://localhost:8080/roller/app/main/entry/40288182103d1af401103d6196
9a0068
Content-Type: application/atom+xml;charset=utf-8
Transfer-Encoding: chunked
Date: Sat, 20 Jan 2007 02:41:51 GMT

3fb
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Blogapps supports Atom (Java)</title>
  <link rel="alternate" href="http://localhost:8080/roller/main/entry/blogapps_s
upports_atom_java1" />
  <link rel="edit" href="http://localhost:8080/roller/app/main/entry/40288182103
d1af401103d61969a0068" />
  <category term="/Java" />
  <author>
    <name>admin</name>
...

Однако если вы попробуете добавить новую категорию, результат будет зависеть от того, как настроен сервер. Например, вы можете попробовать добавить запись с несуществующей категорией (Листинг 4).

Листинг 4. Использование несуществующей категории

                
...
    <summary>The spec's not actually out yet, but fortunately, 
             you can still use it.</summary>
    <published>2007-05-25T08:29:29-04:00</published>
    <category term="NewCategory" />
    <author>
      <name>Nick Chase</name>
      <uri>http://www.chaosmagnet.com</uri>
...

Если вы попробуете отправить этот запрос серверу, результат может быть не таким, каким вы его ожидаете увидеть (см. Листинг 5).

Листинг 5. Результат

                
...
  <link rel="edit" href="http://localhost:8080/roller/app/main/entry/40288182103
d1af401103d62f0ea0069" />
  <category term="/General" />
  <author>
    <name>admin</name>
...

Обратите внимание, что система, вместо того чтобы добавить новую категорию, использовала одну из существующих категорий. Если вы посмотрите назад, на сервисный документ, представленный в Листинге 1, вы увидите, что элементы категорий определяют их как fixed . Это означает, что перечисленные категории - единственно возможные.

Документы категорий

Кроме того, категории могут быть перечислены в отдельных документах. В этом случае в сервисном документе приводится указатель на этот документ. Пример приведен в Листинге 6.

Листинг 6. Указатель на документ категории

                
<?xml version="1.0" encoding="UTF-8"?>
<app:service xmlns:app="http://purl.org/atom/app#" 
             xmlns:atom="http://www.w3.org/2005/atom">
  <app:workspace>
    <atom:title>AdminBlog</atom:title>
    <app:collection 
         href="http://localhost:8080/roller/app/adminblog/entries">
      <atom:title>Weblog Entries</atom:title>
      <app:categories 
                href="http://localhost:8080/roller/adminCategories" />
      <app:accept>entry</app:accept>
    </app:collection>
    <app:collection 
          href="http://localhost:8080/roller/app/adminblog/resources">
      <atom:title>Media Files</atom:title>
      <app:accept>image/*</app:accept>
    </app:collection>
  </app:workspace>
...
</app:service>

В этом случае атрибуты fixed и scheme можно не указывать, однако ничто не мешает вам указать их непосредственно в документе категорий.

Заключение

Главная проблема использования категорий в Atom заключается в знании того, где их искать (сервисный документ), и какие из них допустимы. Когда вы узнаете, какие категории доступны, вы можете просто добавить к записям элементcategory.

Организация контента с помощью категорий Atom (исходники)

Допустимые категории

Использование категорий

Документы категорий

Заключение