Preface

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

Scope

This document contains the specification of the LiveSupport Local storage 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 Local storage component is to store Audio Clips locally.

Goals

The goal of the local storage system is to store Audio Clips locally. Audio Clips contain audio data bundled with metadata describing it. Storing locally means that the binary audio data is available not just as a stream, but also as random seekable file.

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 seekable 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	local interface	locally callable API	must
A1.4	supported audio formats	Ogg Vorbis, MP3, wav	must
A1.5	file system level interface	adding, updated and delete from the local storage can be done by moving files within the file system by legacy tools	frill
A1.6	uniquely identifiable Audio clips	all audio clips should be uniquely identifiable, even when moved among Local storage systems	must

Attributes related to system functions

ref#	function	ref#	attribute	details and constraints	category
F1.2	Provide seekable access to audio data	A1.3	provide file handle	provide randomly seekable file level access to 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	Storage maintainer
purpose	To store a new Audio clip in the local storage, or update (replace) an already stored Audio clip
overview	The Storage maintainer contacts the Local storage with the aim of uploading and storing a new Audio Clip. If the uploaded Audio clip is already stored in Local storage (with respect of having the same unique id), the stored one is replaced with the uploaded one.
references	F1.1, F1.4, A1.6

Typical course of events

actor action		system response
1.	Storage maintainer connects to the Local storage with the intention of storing an Audio clip
2.	The Storage maintainer provides authentication information	3.	The system authenticates the Storage maintainer and grants access.
4.	The Storage 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 Storage maintainer of the actions taken and the unique id of the stored clip.
8.	The Storage maintainer disconnects

Alternate courses

action 3: if the Storage maintainer can not be authenticated, he is notified, and the use case ends.
action 6.2: if the raw audio data of the Audio clip is currently being accessed (see UC-4), it can not be deleted. the user is notified and the use case ends.

UC-2 Delete Audio clip

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

Typical course of events

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

Alternate courses

action 3: if the Storage 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 Storage maintainer is notified. the use case ends.
action 5: if the raw audio data of the Audio clip is currently being accessed (see UC-4), it can not be deleted. the user is notified and the use case ends.

UC-3 Update Audio clip metadata

ref#	UC-3
use case	Update Audio clip metadata
type	primary, essential
actors	Storage maintainer
purpose	To update the metadata of an Audio clip, without uploading raw audio data again.
overview	The Storage maintainer contacts the Local storage 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.	Storage maintainer connects to the Local storage with the intention of updating the metadata for an Audio clip
2.	The Storage maintainer provides authentication information	3.	The system authenticates the Storage maintainer and grants access.
4.	The Storage maintainer presents the unique id of an Audio clip stored in Local storage 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 Storage maintainer disconnects

Alternate courses

action 3: if the Storage 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 Storage maintainer is notified. the use case ends.

UC-4 Access raw audio data

ref#	UC-4
use case	Access raw audio data
type	primary, essential
actors	Audio player
purpose	To access raw audio of Audio clips stored in the Local storage.
overview	The Audio player accesses the raw audio data with the ability of randomly seeking in it.
references	F1.2, A1.3

Typical course of events

actor action		system response
1.	Audio player connects to the Local storage with the intention of accessing raw audio data
2.	The Audio player provides authentication information	3.	The system authenticates the Audio player and grants access.
4.	The Audio player presents the unique id of an Audio clip stored in Local storage that he wants to access	5.	The systems looks up the Audio clip, and provides a seekable handle to the Audio player
6.	The Audio player accesses the raw audio data, including seeking in it.
7.	The Audio player closes it's access and disconnects

Alternate courses

action 3: if the Audio player 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 Audio player is notified. the use case ends.

UC-5 Search in metadata

ref#	UC-5
use case	Search in metadata
type	primary, essential
actors	Storage maintainer
purpose	To search in the metadata of audio clips
overview	The Storage maintainer 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.	Storage maintainer connects to the Local storage with the intention of searching.
2.	The Storage maintainer provides authentication information	3.	The system authenticates the Storage maintainer and grants access.
		4.	The system provides a way of specifying search criteria with respect to the existing metadata structures
5.	The Storage maintainer specifies a search criteria	6.	The system searches through the metadata of contained Audio clips, and presents a list of matches
7.	The Storage maintainer refines his search and searches again	8.	The system does a new search according to the refined criteria, and presents the results to the Storage maintainer
9.	The storage maintainer reviews the results
10.	The storage maintainer disconnects

Alternate courses

action 3: if the Storage maintainer 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 Local storage
RawAudioData	The binary audio data contained in an Audio clip
Storage maintainer	The actor that maintains the contents of the Local storage
Audio player	The actor that accesses the raw audio contained in the Local storage

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
Storage maintainer	Is Authenticated by	Authentication
Storage maintainer	Searches in	MetaData
Storage maintainer	Searches by	SearchCriteria	The storage maintainer specifies such a SearchCriteria when doing a search on MetaData
Storage maintainer	Manages	AudioClip	This includes uploading, updating and deleting AudioClips
Audio player	Is Authenticated by	Authentication
Audio player	Accesses	RawAudioData	This is a seekable access to raw audio data.

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 Access raw audio data

UC-5 Search in metadata

System objects

The following figure 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 Local storage : authenticate

see Authentication : Authenticate

Contract for Local storage : existsAudioClip

Name	existsAudioClip (audioClipId : UniqueId) : boolean
Responsibilities	Check if an Audio clip with the specified id is stored in local storage
Type	system
Cross-reference	none
Notes	none
Exceptions	none
Output	true if an Audio clip with the specified id is stored in Local storage, false otherwise
Pre-conditions	none
Post-conditions	none

Contract for Local storage : 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 AudioClip is is being accessed (see UC-4), report as an error.
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 Local storage : 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. if the RawAudioData for AudioClip is being accessed (see UC-4), report as an error.
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 Local storage : updateAudioClipMetadata

Name	updateAudioClipMetadata (audioClipId : UniqueId, newMetadata : MetaData) : void
Responsibilities	Update the metadata of an Audio clip stored in Local storage
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 Local storage : accessRawAudioData

Name	accessRawAudioData (audioClipId : UniqueId) : RawAudioData
Responsibilities	Get access to raw audio data of an AudioClip
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 for the AudioClip identified with the supplied UniqueId
Pre-conditions	none
Post-conditions	condition	type
	the currentlyAccessing attribute for RawAudioData for AudioClip is increased by one	attribute modification

Contract for Local storage : releaseRawAudioData

Name	releaseRawAudioData (rawAudioData : RawAudioData) : void
Responsibilities	Release access for raw audio data
Type	system
Cross-reference	UC-4
Notes	none
Exceptions	if the specified RrawAudioData is not stored in Local storage, indicate as an error
Output	none
Pre-conditions	none
Post-conditions	condition	type
	the currentlyAccessing attribute for RawAudioData for AudioClip is decreased by one	attribute modification

Contract for Local storage : 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

Contract for Local storage : getAudioClip

Name	getAudioClip (audioClipId : UniqueId) : AudioClip
Responsibilities	Return the contents of an Audio clip.
Type	system
Cross-reference	see Playlist editor
Notes	none
Exceptions	if no Audio clip by the specified id exists, report as an error.
Output	The Audio clip, specified by the supplied id.
Pre-conditions	none
Post-conditions	none