Preface

Author: $Author: maroy $
Version: $Revision: 1.1 $
Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/model/MediaArchive/index.html,v $

Scope

This document contains the specification of the LiveSupport Media archive component.

This document contains embedded SVG figures, thus an SVG capable browser is needed to view it, or an SVG plugin like Adobe's SVG Viewer.

Requirements

Overview

The purpose of the Media archive is to store Audio clips with metadata information, and offer remote access to these clips.

Goals

The goal of the Media storage system is to store Audio Clips and share them over the network. Another aim is to provide extensive search possibilities based on the metadata bundled with the audio clips.

System functions

The main system functions are described below. There are three categories for these functions:

function category	meaning
evident	Should perform, and the user should be cognizant that it is performed
hidden	Should perform, but not visible to the users.
frill	Optional

ref#	function	category
F1.1	Store audio clips	evident
F1.2	Provide remote access to audio data	evident
F1.3	Delete stored clips	evident
F1.4	Update stored clips	evident
F1.5	Search Audio clips by querying metadata	evident

System attributes

Generic attributes

ref#	attribute	details and constraints	category
A1.1	operating system platform	Linux	must
A1.2	remote interface	the Media archive is remotely accessible	must
A1.3	supported audio formats	Ogg Vorbis, MP3, wav	must
A1.4	uniquely identifiable Audio clips	all audio clips should be uniquely identifiable, even when moved among Media archive systems	must
A1.6	consistent downloads during updates	when an audio clip is being updated while also being downloaded, make sure that the downloads can continue with the original content	frill

Attributes related to system functions

ref#	function	ref#	attribute	details and constraints	category
F1.2	Provide remote access to audio data	A1.5	partial downloads	provide the possibility of interrupted (partial) downloads of raw audio data	must

Essential use cases

This section lists generic (essential) uses cases, that do not contain architecture-specific considerations.

UC-1 Store or update Audio clip

ref#	UC-1
use case	Store or update Audio clip
type	primary, essential
actors	Archive maintainer
purpose	To store a new Audio clip in the media archive, or update (replace) an already stored Audio clip
overview	The Archive maintainer contacts the Media archive with the aim of uploading and storing a new Audio Clip. If the uploaded Audio clip is already stored in Media archive (with respect of having the same unique id), the stored one is replaced with the uploaded one.
references	F1.1, F1.4, A1.4

Typical course of events

actor action		system response
1.	Archive maintainer connects to the Media archive with the intention of storing an Audio clip
2.	The Archive maintainer provides authentication information	3.	The system authenticates the Archive maintainer and grants access.
4.	The Archive maintainer presents the new Audio clip data, including raw audio data and metadata	5.	The system verifies the received data
		6.1	If the presented Audio clip does not contain a unique id, one is generated.
		6.2	If the presented Audio clip contains a unique id, and there already is an Audio clip stored with the same id, the stored one is replaced with the uploaded Audio clip.
		7.	The system stores the received Audio clip and notifies the Archive maintainer of the actions taken and the unique id of the stored clip.
8.	The Archive maintainer disconnects

Alternate courses

action 3: if the Archive maintainer can not be authenticated, he is notified, and the use case ends.
action 6.2: TODO: handle the case of the raw audio data of the Audio clip is currently being downloaded (see UC-4, A1.6)

UC-2 Delete Audio clip

ref#	UC-2
use case	Delete Audio clip
type	primary, essential
actors	Archive maintainer
purpose	To delete an existing Audio clip in the media archive
overview	The Archive maintainer contacts the Media archive with the aim of deleting an existing Audio Clip
references	F1.3

Typical course of events

actor action		system response
1.	Archive maintainer connects to the Media archive with the intention of deleting an Audio clip
2.	The Archive maintainer provides authentication information	3.	The system authenticates the Archive maintainer and grants access.
4.	The Archive maintainer presents the unique id of an Audio clip stored in Media archive for deletion	5.	The system deletes the Audio clip corresponding to the presented unique id.
6.	The Archive maintainer disconnects

Alternate courses

action 3: if the Archive maintainer can not be authenticated, he is notified, and the use case ends.
action 5: if no Audio clip is stored with the presented id, the Archive maintainer is notified. the use case ends.
action 5: TODO: handle the case of the raw audio data of the Audio clip is currently being downloaded (see UC-4, A1.6)

UC-3 Update Audio clip metadata

ref#	UC-3
use case	Update Audio clip metadata
type	primary, essential
actors	Archive maintainer
purpose	To update the metadata of an Audio clip, without uploading raw audio data again.
overview	The Archive maintainer contacts the Media archive with the aim of updating the metadata for an already stored Audio clip
references	F1.4

Typical course of events

actor action		system response
1.	Archive maintainer connects to the Media archive with the intention of updating the metadata for an Audio clip
2.	The Archive maintainer provides authentication information	3.	The system authenticates the Archive maintainer and grants access.
4.	The Archive maintainer presents the unique id of an Audio clip stored in Media archive and the new metadata for that Audio clip	5.	The system verifies the clip id and the metadata
		6.	The system replaces the metadata of the Audio clip with the presented one
7.	The Archive maintainer disconnects

Alternate courses

action 3: if the Archive maintainer can not be authenticated, he is notified, and the use case ends.
action 5: if no Audio clip is stored with the presented id, the Archive maintainer is notified. the use case ends.

UC-4 Download raw audio data

ref#	UC-4
use case	Download audio data
type	primary, essential
actors	Archive client
purpose	To download raw audio data stored in the Media archive
overview	The Archive client downloads the raw audio data.
references	F1.2, A1.3

Typical course of events

actor action		system response
1.	Archive client connects to the Media archive with the intention of downloading raw audio data
2.	The Archive client provides authentication information	3.	The system authenticates the Archive client and grants access.
4.	The Archive client presents the unique id of an Audio clip stored in Media archive that he wants to download	5.	The systems looks up the Audio clip, and starts to send the raw audio content as a stream
6.	The Archive client receives the stream of raw audio data and saves it.
7.	The Archive client closes it's access and disconnects

Alternate courses

action 3: if the Archive client can not be authenticated, he is notified, and the use case ends.
action 4: the Archive client specifies an offset from which he wants to start a partial download. the system starts to send raw audio data from this offset in action 5.
action 5: if no Audio clip is stored with the presented id, the Archive client is notified. the use case ends.

UC-5 Search in metadata

ref#	UC-5
use case	Search in metadata
type	primary, essential
actors	Archive client
purpose	To search in the metadata of audio clips
overview	The Archive client searches through the stored Audio clips by specifying search criteria for the metadata of the clips
references	F1.5

Typical course of events

actor action		system response
1.	Archive client connects to the Media archive with the intention of searching.
2.	The Archive cleint provides authentication information	3.	The system authenticates the Archive client and grants access.
		4.	The system provides a way of specifying search criteria with respect to the existing metadata structures
5.	The Archive client specifies a search criteria	6.	The system searches through the metadata of contained Audio clips, and presents a list of matches
7.	The Archive client refines his search and searches again	8.	The system does a new search according to the refined criteria, and presents the results to the Archive client
9.	The Archive client reviews the results
10.	The Archive client disconnects

Alternate courses

action 3: if the Archive client can not be authenticated, he is notified, and the use case ends.

Conceptual model

The following figure displays the semantic concepts identified for the Scheduler daemon, and the main associations between the concepts.

Concepts

concept	description
Authentication	Component responsible for doing the authentications
Unique Id	A globally unique identifier used to to differentiate between objects that might even be created on different systems. Even though the whole space of Id is not known, the Ids must be unique.
MetaData	Data about the AudioClip
SearchCriteria	Describes the search parameters when doing a search on the MetaData
AudioClip	The basic unit of audio handled by Media archive
RawAudioData	The binary audio data contained in an Audio clip
Archive maintainer	The actor that maintains the contents of the Media archive
Archive client	The actor that accesses the data stored in the Media archive

Associations

source	association	target	description
AudioClip	Is identified by	UniqueId	This is a globally unique id for each Audio clip
AudioClip	Is described by	MetaData
AudioClip	Contains	RawAudioData
Archive maintainer	Is Authenticated by	Authentication
Archive client	Searches in	MetaData
Archive client	Searches by	SearchCriteria	The Archive client specifies such a SearchCriteria when doing a search on MetaData
Archive maintainer	Manages	AudioClip	This includes uploading, updating and deleting AudioClips
Archive client	Is Authenticated by	Authentication
Archice client	Downloads	RawAudioData	Download RawAudioData as a binary stream.

System behavior

The behavior of the system as a whole as experienced from the outside is discussed in this section.

System sequence diagrams

System diagrams are presented for each use case below.

UC-1 Store or update Audio clip

UC-2 Delete Audio clip

UC-3 Update Audio clip metadata

UC-4 Download raw audio data

UC-5 Search in metadata

System objects

The following figures shows the system objects and their functions, as derived from the system sequence diagrams.

Contracts

For all operations exposed in the system sequence diagrams, the following contracts are defined.

Contract for Media archive : authenticate

see Authentication : Authenticate

Contract for Media archive : storeAudioClip

Name	storeAudioClip (audioClip : AudioClip) : UniqueId
Responsibilities	Store a new audio clip or replace an existing one.
Type	system
Cross-reference	UC-1
Notes	none
Exceptions	if this is an AudioClip update, and the RawAudioData of the already existing TODO: handle the case of the raw audio data of the Audio clip is currently being downloaded (see UC-4, A1.6)
Output	the unique id of the stored audio clip
Pre-conditions	none
Post-conditions	condition	type
if this is a new audio clip:	an AudioClip object is created	instance creation
	a UniqueId is generated for the new clip	instance creation
	the UniqueId is associated with the AudioClip	association formed
	a MetaData object is created and filled with the presented contents	instance creation
	the MetaData is associated with the AudioClip	association formed
	a RawAudioData object is created and filled with the presented contents	instance creation
	the RawAudioData is associated with the AudioClip	association formed
if the clip already existed:	the contents of MetaData for the AudioClip are replaced by the presented contents	attribute modification
	the contents of RawAudioData for the AudioClip are replaced by the presented contents	attribute modification

Contract for Media archive : deleteAudioClip

Name	deleteAudioClip (audioClipId : UniqueId) : void
Responsibilities	Delete an existing Audio clip
Type	system
Cross-reference	UC-2
Notes	none
Exceptions	if no Audio clip with the specified id exists, report as an error. TODO: handle the case of the raw audio data of the Audio clip is currently being downloaded (see UC-4, A1.6)
Output	none
Pre-conditions	none
Post-conditions	condition	type
	the UniqueId for the AudioClip is deleted	instance deletion
	the MetaData for the AudioClip is deleted	instance deletion
	the RawAudioData for the AudioClip is deleted	instance deletion
	the AudioClip is deleted	instance deletion

Contract for Media archive : updateAudioClipMetadata

Name	updateAudioClipMetadata (audioClipId : UniqueId, newMetadata : MetaData) : void
Responsibilities	Update the metadata of an Audio clip stored in Media archive
Type	system
Cross-reference	UC-3
Notes	none
Exceptions	if no Audio clip with the specified id exists, report as an error.
Output	none
Pre-conditions	none
Post-conditions	condition	type
	the contents of MetaData for the AudioClip are replaced with the presented contents	attribute modification

Contract for Media archive : accessRawAudioData

Name	downloadRawAudioData (audioClipId : UniqueId, offset : int) : RawAudioData
Responsibilities	Get access to raw audio data of an AudioClip as a data stream.
Type	system
Cross-reference	UC-4
Notes	none
Exceptions	if no Audio clip with the specified id exists, report as an error.
Output	the RawAudioData as a stream for the AudioClip identified with the supplied UniqueId, started at the specified offset.
Pre-conditions	none
Post-conditions	none

Contract for Media archive : searchMetadata

Name	searchMetadata (criteria : SearchCriteria) : UniqueId
Responsibilities	Search through the metadata of stored AudioClips, and return all matching clip ids
Type	system
Cross-reference	UC-5
Notes	none
Exceptions	none
Output	A range of Audio clip ids, for which MetaData matches the supplied search criteria
Pre-conditions	none
Post-conditions	none