Preface

Author: $Author: fgerlits $
Version: $Revision: 1.4 $
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.
The local storage contains Playlists also. These are metadata files containing a list of Audio Clip IDs with extra (fade in / fade out) information.

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
F2.1	Create new playlists	evident
F2.2	Access playlists for editing	evident
F2.3	Delete playlists	evident
F2.4	Access playlists for execution	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.

UC-6 Create playlist

ref#	UC-6
use case	Create playlist
type	primary, essential
actors	Storage maintainer
purpose	To store a new Playlist in the local storage
overview	The Storage maintainer contacts the Local storage with the aim of uploading a new Playlist. The Local storage stores the new metafile under the new ID.
references	F2.1

Typical course of events

actor action		system response
1.	Storage maintainer connects to the Local storage with the intention of uploading a new Playlist
2.	The Storage maintainer provides authentication information	3.	The system authenticates the Storage maintainer and grants access.
4.	The Storage maintainer presents the new Playlist ID and the new Playlist metafile	5.	The system verifies that there is no Playlist yet in the Local storage with the given ID
		6.	The system stores the received Playlist metafile and notifies the Storage maintainer of the action taken.
7.	The Storage maintainer disconnects

Alternate courses

action 3: if the Storage maintainer can not be authenticated, she is notified, and the use case ends.
action 5: if there is already a Playlist in the Local storage with the given ID, the user is notified and the use case ends.

UC-7 Edit playlist

ref#	UC-7
use case	Edit playlist
type	primary, essential
actors	Storage maintainer
purpose	To modify an existing Playlist in the local storage
overview	The Storage maintainer contacts the Local storage with the aim of editing an existing Playlist. The Local storage retrieves the Playlist and marks it as being edited. The Storage maintainer modifies the Playlist. The Storage maintainer saves the modified Playlist, the Local storage stores it in place of the old Playlist and marks it as no longer being edited.
references	F2.2

Typical course of events

actor action		system response
1.	Storage maintainer connects to the Local storage with the intention of editing a Playlist
2.	The Storage maintainer provides authentication information	3.	The system authenticates the Storage maintainer and grants access
4.	The Storage maintainer presents a Playlist ID	5.	The system verifies that there is a Playlist in the Local storage with the given ID, and it is not currently being edited
		6.	The system marks the Playlist with the given ID as being edited
		7.	The system returns the Playlist metafile with the given ID and notifies the Storage maintainer of the actions taken
8.	The Storage maintainer modifies the Playlist
9.	The Storage maintainer presents the new Playlist metafile for saving	10.	The system verifies that the user had opened this Playlist earlier
		11.	The system stores the new Playlist metafile in place of the old one, marks it as no longer being edited, and notifies the Storage maintainer of the actions taken
12.	The Storage maintainer disconnects.

Alternate courses

action 3: if the Storage maintainer can not be authenticated, she is notified, and the use case ends.
action 5: if there is no Playlist in the Local storage with the given ID, or if the Playlist is already being edited, the user is notified and the use case ends.
action 10: if the user cannot be identified as the same that opened the Playlist for editing, the user is notified, and the use case continues at point 8.

UC-8 Delete playlist

ref#	UC-8
use case	Delete playlist
type	primary, essential
actors	Storage maintainer
purpose	To delete a Playlist from the local storage
overview	The Storage maintainer contacts the Local storage with the aim of deleting a Playlist. The system deletes the Playlist with the given ID from the Local storage.
references	F2.3

Typical course of events

actor action		system response
1.	Storage maintainer connects to the Local storage with the intention of deleting a Playlist
2.	The Storage maintainer provides authentication information	3.	The system authenticates the Storage maintainer and grants access
4.	The Storage maintainer presents the ID of the Playlist to be deleted	5.	The system verifies that there is a Playlist in the Local storage with the given ID, and it is not currently being edited
		6.	The system deletes the given Playlist from the Local storage and notifies the Storage maintainer of the action taken
7.	The Storage maintainer disconnects.

Alternate courses

action 3: if the Storage maintainer can not be authenticated, she is notified, and the use case ends.
action 5: if there is no Playlist in the Local storage with the given ID, or if the Playlist is currently being edited, the user is notified and the use case ends.

UC-9 Access playlist

ref#	UC-9
use case	Access playlist
type	primary, essential
actors	Audio player
purpose	To access a Playlist metafile in order to execute (play) it
overview	The Audio player contacts the Local storage with the aim of accessing a Playlist. The Local storage returns the requested Playlist metafile.
references	F2.4

Typical course of events

actor action		system response
1.	Audio player connects to the Local storage with the intention of accessing a Playlist
2.	The Audio player provides authentication information	3.	The system authenticates the Audio player and grants access
4.	The Audio player presents a Playlist ID	5.	The system verifies that there is a Playlist in the Local storage with the given ID
		6.	The system returns the requested Playlist metafile and notifies the Audio player of the action taken
7.	The Audio player reads the Playlist, and saves a private copy
8.	The Audio player notifies the Local storage that it no longer needs the Playlist, and disconnects.

Alternate courses

action 3: if the Audio player can not be authenticated, she is notified, and the use case ends.
action 5: if there is no Playlist in the Local storage with the given ID, the user 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
Session ID	An identifier issued by Authentication, to be used by subsequent operations.
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
Playlist	A metafile containing AudioClip IDs and some extra (fade in / fade out) information
URL	The location of a metafile (in the local filesystem)
Token	An identifier used to match the parts of two-part operations, e.g., access--release or edit--save

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.
Playlist	Is identified by	UniqueId	This is a globally unique id for each Playlist
Storage maintainer	Manages	Playlist	This includes creating, editing, deleting and accessing Playlists
Playlist	Is associated with	URL	The path of (a copy of) the playlist metafile
Playlist	Is associated with	Token	An identifier issued by access operations, to be used for identification by release operations

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

UC-6 Create playlist

UC-7 Edit playlist

UC-8 Delete playlist

UC-9 Access playlist

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 (sessionId : SessionId, 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 (sessionId : SessionId, 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 (sessionId : SessionId, 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 (sessionId : SessionId, 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 (sessionId : SessionId, 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 (sessionId : SessionId, 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 (sessionId : SessionId, 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 (sessionId : SessionId, 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

Contract for Local storage : createPlaylist

Name	createPlaylist (sessionId : SessionId, playlistId : UniqueId) : void
Responsibilities	Create a new Playlist metafile.
Type	system
Cross-reference	UC-6
Notes	none
Exceptions	if a Playlist with the given playlistId already exists, report as an error
Output	none
Pre-conditions	none
Post-conditions	condition	type
	a Playlist object is created	instance creation
	the new Playlist is marked as currently not being edited	attribute modification

Contract for Local storage : editPlaylist

Name	editPlaylist (sessionId : SessionId, playlistId : UniqueId) : { playlistURL : URL, playlistToken: Token }
Responsibilities	Open a Playlist metafile for editing.
Type	system
Cross-reference	UC-7
Notes	none
Exceptions	if no Playlist with the given playlistId exists, or if the Playlist has already been marked as being edited, report as an error
Output	a URL of a Playlist metafile, and a token identifying it
Pre-conditions	none
Post-conditions	condition	type
	the Playlist is marked as currently being edited	attribute modification
	the Playlist metafile and the URL returned are associated with the token returned	association formed

Contract for Local storage : savePlaylist

Name	savePlaylist (sessionId : SessionId, playlistToken : Token, newPlaylist : Playlist) : void
Responsibilities	Store a new Playlist metafile in place of the old one.
Type	system
Cross-reference	UC-7
Notes	TODO: decide exactly what the newPlaylist argument looks like
Exceptions	if the playlistToken argument does not match a token generated earlier in this session by editPlaylist(), report as an error
Output	none
Pre-conditions	the Playlist has been marked as being edited in the same session
Post-conditions	condition	type
	the Playlist is marked as currently not being edited	attribute modification
	the playlistToken token and the URL returned earlier by editPlaylist() together with it are no longer valid	association broken

Contract for Local storage : deletePlaylist

Name	deletePlaylist (sessionId : SessionId, playlistId : UniqueId) : void
Responsibilities	Delete a Playlist metafile.
Type	system
Cross-reference	UC-8
Notes	none
Exceptions	if no Playlist with the given playlistId exists, or if the Playlist is marked as currently being edited, report as an error
Output	none
Pre-conditions	none
Post-conditions	condition	type
	a Playlist object is deleted	instance deletion

Contract for Local storage : accessPlaylist

Name	accessPlaylist (sessionId : SessionId, playlistId : UniqueId) : { playlistURL : URL, playlistToken : Token }
Responsibilities	Access (read) a Playlist metafile.
Type	system
Cross-reference	UC-9
Notes	for this method, it does not matter whether the Playlist is being edited or not -- the latest saved state of the Playlist should be returned
Exceptions	if no Playlist with the given playlistId exists, report as an error
Output	a URL of a Playlist metafile, and a token identifying it
Pre-conditions	none
Post-conditions	condition	type
	the Playlist and the URL returned are associated with the token returned	association formed

Contract for Local storage : releasePlaylist

Name	releasePlaylist (sessionId : SessionId, playlistToken : Token) : void
Responsibilities	Release the resources obtained earlier by accessPlaylist().
Type	system
Cross-reference	UC-9
Notes	none
Exceptions	if the playlistToken argument does not match a token generated earlier in this session by accessPlaylist(), report as an error
Output	none
Pre-conditions	none
Post-conditions	condition	type
	the playlistToken token and the URL returned earlier by accessPlaylist() together with it are no longer valid	association broken

Contract for Local storage : existsPlaylist

Name	existsPlaylist (sessionId : SessionId, playlistId : UniqueId) : bool
Responsibilities	Check whether a Playlist metafile with the given playlist ID exists.
Type	system
Cross-reference	UC-6, UC-7, UC-8, UC-9
Notes	none
Exceptions	none
Output	true or false
Pre-conditions	none
Post-conditions	none

Contract for Local storage : playlistIsAvailable

Name	playlistIsAvailable (sessionId : SessionId, playlistId : UniqueId) : bool
Responsibilities	Check whether a Playlist metafile with the given playlist ID is available for editing, i.e., exists and has not been opened for editing yet.
Type	system
Cross-reference	UC-7
Notes	none
Exceptions	none
Output	true if the playlist exists and is available; false if either condition fails
Pre-conditions	none
Post-conditions	none

Contract for Local storage : accessAudioClip

Name	accessAudioClip (sessionId : SessionId, audioClipId : UniqueId) : { audioClipURL : URL, audioClipToken : Token }
Responsibilities	Access (read) an Audio Clip metafile.
Type	system
Cross-reference	UC-4
Notes	none
Exceptions	if no AudioClip with the given audioClipId exists, report as an error
Output	a URL of an AudioClip metafile, and a token identifying it
Pre-conditions	none
Post-conditions	condition	type
	the AudioClip and the URL returned are associated with the token returned	association formed

Contract for Local storage : releaseAudioClip

Name	releaseAudioClip (sessionId : SessionId, audioClipToken : Token) : void
Responsibilities	Release the resources obtained earlier by accessAudioClip().
Type	system
Cross-reference	UC-4
Notes	none
Exceptions	if the audioClipToken argument does not match a token generated earlier in this session by accessAudioClip(), report as an error
Output	none
Pre-conditions	none
Post-conditions	condition	type
	the audioClipToken token and the URL returned earlier by accessAudioClip() together with it are no longer valid	association broken