Page History

...

Prior to this implementation, there was a dummy service document provided when you visited an Atom feed service address with an "atomsvc" extension. For example, running the the Atom service binding unit tests, one could visit http://localhost:8080/customer/atomsvc^{Image Removed} and receive the following service document:

...

Following the inclusion of TUSCANY-2597 and the new implentation, the Tuscany Atom binding will correctly populate an atomsvc document with information from the feed and give correct information for discovery. Now , running the the Atom service binding unit tests, one could visit http://localhost:8080/customer/atomsvc^{Image Removed} and receive the following service document:

...

This item implemented by TUSCANY-2567.

"- support for postMedia and putMedia, including the ability to stream that content in the target application component "

Streaming, in the "large media" sense of the word, is defined to mean the use of a content stream before the entire content is downloaded or available. For example, streaming video or audio means that the large video or audio file is played before the entire program is downloaded and available. Usually streaming entails downloading chunks of a media stream, playing the available chunks, and perhaps discarding or saving older chunks in order to download and play new ones.

At the time of this writing (2008-09-24), Tuscany does not actively support streaming of media content, as defined by the Atom Publishing Protocol. However, it is still possible to implement.

The Atom Publishing Protocol provides for a separate space for storage of media resources. The purpose of a separate space for these resources is to keep feeds and entries from growing too large with the contents of typically large items. Media resources can be any binary object that is supported by a MIME type, but typically media resources include video, image, and audio type files.

Media resources are maintained by the collection implementor, and are given a dual identity. There is a location in the media respository, typically where one places the media files, and there is a location in the feed or entry space. This second reference is known as a media link entry.

The Tuscany package at orgFor example, the Tuscany package at or.apache.tuscany.sca.binding.atom.collection (in tuscany-binding-atom-abdera package) has the following interface for MediaCollection:

   /**
     * Creates a new media entry
     * 
     * @param title
     * @param slug
     * @param contentType
     * @param media
     */
    Entry postMedia(String title, String slug, String contentType, InputStream media);

    /**
     * Update a media entry.
     * 
     * @param id
     * @param contentType
     * @param media
     * @return
     */
    void putMedia(String id, String contentType, InputStream media) throws NotFoundException;

It is entirely possible to create a streaming collection implementation for postMedia and putMedia using this interface. Note that the InputStream containing the media bytes can be used to create a stream reader that reads the media object. Using the contentType String with the stream MIME type, the stream reader can read and stream the content given.

Similarly, a GET media interface can be created and an intelligent stream reader can read the media stream to stream.

These two methods are used to create (post) new media files, and update (put) new media information and edits. The media resources may be retrieved (get) or removed (delete) via the normal HTTP get and delete operations and the links returned by the post and get methods.

For instance, when creating a media resource, one typically posts the following information via an HTTP post request:

POST /edit/ HTTP/1.1
Host: media.example.org
Content-Type: image/png
Slug: The Beach
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn
...binary data...

In turn, the Tuscany invocation framework invokes the postMedia shown above on the media collection implementation. The media collection implementation may then take the binary data from the media InputStream and store it to a media repository. The media collection implemenation should construct a proper Entry item via XML construction or some Atom model framework such as Apache Abdera. The Entry should contain the required elements (title, id, updated, summary, content, edit link, edit-media link) in order to provide the proper Atom Pub Protocol return headers and Entry data as given here:

HTTP/1.1 201 Created
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/media/edit/the_beach.atom
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
   <title>The Beach</title>
   <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
   <updated>2005-10-07T17:17:08Z</updated>
   <author><name>Daffy</name></author>
   <summary type="text" />
   <content type="image/png"
      src="http://media.example.org/the_beach.png"/>
   <link rel="edit-media"
      href="http://media.example.org/edit/the_beach.png" />
   <link rel="edit"
      href="http://example.org/media/edit/the_beach.atom" />
</entry> 

Note that the edit link provides the Atom Feed link to the media entry, and the edit-media link provides the media repository link to the media entry. Use these links to get and delete media.

A special convention has been implemented to allow the media collection implementation to return properties in the response header. The summary element of the Entry returned may contain a set of key=value properties separated via commas. For example, in order to provide return Content-Type and Content-Length values in the response header, one can created this text in the postMedia Entry summary element: Content-Type=image/jpg,Content-Length=21642.

The putMedia method acts in much the same way, but the URI to the item should contain an ID to the media being updated. For instance, if the usual post and get feed URI is http://localhost:8084/receipt, then to update the media given above one would put to the URI http://localhost:8084/receipt/urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a. Here is an example of a put request:

PUT /edit/urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a HTTP/1.1
Host: media.example.org
Content-Type: image/png
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: nnn 
...binary data...

After the above put request, the Atom binding will invoke the media collection implementation putMedia method. The media collection should update the media if the ID exists (and a 200 OK status code will return), or the media collection should throw a NotFoundException if the ID does not exist (and a 404 not found status code will return).

The above scenarios are documents in the MediaCollectionTestCase unit test case in the binding-atom-abdera module in the Tuscany code baseSo, as of today, Tuscany users can read and stream media collections. However, it is the intention of this JIRA to provide tools or additional classes to help implement streaming.

Security on Sensitive Commands (Delete,DeleteAll,etc.)

...