org.unisens
Interface Unisens

public interface Unisens

Unisens is the basic interface to a unisens dataset. It represents its structure. Each Unisens object is linked to its unisens.xml file, which is contained in every unisens dataset.

Author:

Joerg Ottenbacher, Radi Nedkov, Malte Kirst

Method Summary

void	addCustomAttribute(java.lang.String key, java.lang.String value) Add a ned custom attributes to this unisens dataset.
Entry	addEntry(Entry entry, boolean deepCopy) Add an existing Entry to this unisens dataset.
Group	addGroup(Group group, boolean deepCopy) Add an existing Group and its Entries to this unisens dataset.
void	closeAll() Closes all open Entries contained in this unisens dataset
Context	createContext(java.lang.String schemaUrl) Creates a context information to this uniens dataset.
CustomEntry	createCustomEntry(java.lang.String id) Creates a new CumstomEntry in this unisens dataset.
EventEntry	createEventEntry(java.lang.String id, double sampleRate) Creates a new EventEntry in this unisens dataset.
Group	createGroup(java.lang.String id) Creates a new Group in this unisens dataset.
SignalEntry	createSignalEntry(java.lang.String id, java.lang.String[] channelNames, DataType dataType, double sampleRate) Creates a new SignalEntry in this unisens dataset.
ValuesEntry	createValuesEntry(java.lang.String id, java.lang.String[] channelNames, DataType dataType, double sampleRate) Creates a new ValuesEntry in this unisens dataset.
void	deleteContext() Removes the context information from this unisens dataset.
void	deleteEntry(Entry entry) Delete an Entry from this unisens dataset
void	deleteGroup(Group group) Deletes a Group from this unisens dataset.
java.lang.String	getComment() Gets the comment of this Unisens object.
Context	getContext() Gets the Context of this unisens dataset.
java.util.HashMap<java.lang.String,java.lang.String>	getCustomAttributes() Returns the custom attributes of this unisens dataset.
double	getDuration() Gets the duration of this dataset in seconds.
java.util.List<Entry>	getEntries() Returns a List of all Entries contained in this unisens dataset.
Entry	getEntry(java.lang.String id) Returns the Entry identified by its id.
Group	getGroup(java.lang.String id) Returns the Group identified by its id.
java.util.List<Group>	getGroups() Returns a List of alls Groups contained in this unisens dataset.
java.lang.String	getMeasurementId() Gets the id of this unisens dataset.
java.lang.String	getPath() Returns the path of the dataset represented by this Unisens object.
java.util.Date	getTimestampStart() Gets the timestamp of the start of the data acquisition
java.lang.String	getVersion() Returns the version of the XML-Schema used in the unisens.xml file
void	save() Saves this unisens dataset.
void	setComment(java.lang.String comment) Sets the comment of this Unisens object.
void	setDuration(double duration) Sets the duration of this dataset in seconds.
void	setDuration(long duration) Deprecated. use double parameter instead of long
void	setMeasurementId(java.lang.String id) Gets the id of this unisens dataset.
void	setTimestampStart(java.util.Date timestampStart) Sets the timestamp of the start of the data acquisition

Method Detail

getPath

java.lang.String getPath()

Returns the path of the dataset represented by this Unisens object. The associated unisens.xml file is contained in this path.

Returns:

the path of this Unisens dataset

getComment

java.lang.String getComment()

Gets the comment of this Unisens object. The comment describes the dataset as a whole.

Returns:

the comment of this Unisens object

setComment

void setComment(java.lang.String comment)

Sets the comment of this Unisens object. The comment describes the dataset as a whole.

Parameters:

comment - decription of the whole dataset

getDuration

double getDuration()

Gets the duration of this dataset in seconds. If the dataset contains at least one SignalEntry this information is redundant, because the duration can then be calculated from the length of the SignalEntry.

Returns:

duration of this dataset in seconds.

setDuration

void setDuration(double duration)

Sets the duration of this dataset in seconds. If the dataset contains at least one SignalEntry this information is not needed, because the duration can then be calculated from the length of the SignalEntry.

Parameters:

duration - the duration of this dataset in seconds

setDuration

@Deprecated
void setDuration(long duration)

Deprecated. use double parameter instead of long

Sets the duration of this dataset in seconds. If the dataset contains at least one SignalEntry this information is not needed, because the duration can then be calculated from the length of the SignalEntry.

Parameters:

duration - the duration of this dataset in seconds

See Also:

setDuration(double duration)

getMeasurementId

java.lang.String getMeasurementId()

Gets the id of this unisens dataset. The id can be used to identify a dataset within a database.

Returns:

the Id of this dataset

setMeasurementId

void setMeasurementId(java.lang.String id)

Gets the id of this unisens dataset. The id can be used to identify a dataset within a database.

Parameters:

id - the Id of this dataset.

getTimestampStart

java.util.Date getTimestampStart()

Gets the timestamp of the start of the data acquisition

Returns:

the timestamp of the start of the data acquisition

setTimestampStart

void setTimestampStart(java.util.Date timestampStart)

Sets the timestamp of the start of the data acquisition

Parameters:

timestampStart - the timestamp of the start of the data acquisition

getVersion

java.lang.String getVersion()

Returns the version of the XML-Schema used in the unisens.xml file

Returns:

the Schema Version of the uisens.xml file

getContext

Context getContext()

Gets the Context of this unisens dataset. The associated information is contained in the context.xml file. See the documentation for more information.

Returns:

the Context of this unisens dataset

getEntries

java.util.List<Entry> getEntries()

Returns a List of all Entries contained in this unisens dataset. The Entries can be of the following type:

• SignalEntry
• ValuesEntry
• EventEntry
• CustomEntry

Returns:

the List of Entries in this unisens dataset

getEntry

Entry getEntry(java.lang.String id)

Returns the Entry identified by its id. Within an unisens dataset each entry has a unique id.

Parameters:

id - the id of the Entry

Returns:

Entry identified by id

getGroups

java.util.List<Group> getGroups()

Returns a List of alls Groups contained in this unisens dataset. Semantically related entries can be grouped in a Group.

Returns:

the List of Groupd contained in this unisens dataset.

getGroup

Group getGroup(java.lang.String id)

Returns the Group identified by its id. Within an unisens dataset each group has a unique id.

Parameters:

id - id of the Group.

Returns:

Group identifierd by id

deleteContext

void deleteContext()

Removes the context information from this unisens dataset. The corresponding context.xml file will not be deleted.

deleteGroup

void deleteGroup(Group group)

Deletes a Group from this unisens dataset. The Entries in the group will no be deleted.

Parameters:

group - the Group to be deleted

deleteEntry

void deleteEntry(Entry entry)

Delete an Entry from this unisens dataset

Parameters:

entry - the Entry to be deleted

save

void save()
          throws java.io.IOException

Saves this unisens dataset. The dataset information is stored in the associated unisens.xml file.

Throws:

java.io.IOException

createContext

Context createContext(java.lang.String schemaUrl)

Creates a context information to this uniens dataset. The context information hast to be available in the context.xml file. The structure of the context.xml file is described by a XML-Schema.

Parameters:

schemaUrl - the URL to the XML schema describing the structure of context.xml

Returns:

the created Context

createGroup

Group createGroup(java.lang.String id)
                  throws DuplicateIdException

Creates a new Group in this unisens dataset. Within a dataset groups have to have a unique id.

Parameters:

id - the id of the Group

Returns:

the created Group

Throws:

DuplicateIdException

createSignalEntry

SignalEntry createSignalEntry(java.lang.String id,
                              java.lang.String[] channelNames,
                              DataType dataType,
                              double sampleRate)
                              throws DuplicateIdException

Creates a new SignalEntry in this unisens dataset. A SignalEntry represents continuously sampled data. A file containing the associated data is also created if not already present. The filename is the same as the id of the Entry.

Parameters:

id - the id of the Entry. Has to be unique within one unisens dataset

channelNames - an Array of names of the channels. At least on channel has to be present.

dataType - the DataType of the data contained in this SignalEntry.

sampleRate - the sampleRate of the data in samples per second.

Returns:

the created SignalEntry

Throws:

DuplicateIdException

createEventEntry

EventEntry createEventEntry(java.lang.String id,
                            double sampleRate)
                            throws DuplicateIdException

Creates a new EventEntry in this unisens dataset. An EventEntry represents Events at certain points in time. Events have no data value. A file containing the associated data is also created if not already present. The filename is the same as the id of the Entry.

Parameters:

id - the id of the Entry. Has to be unique within one unisens dataset.

sampleRate - the sampleRate of the data in samples per second. Points if time are given as sample counts

Returns:

the created EventEntry

Throws:

DuplicateIdException

createValuesEntry

ValuesEntry createValuesEntry(java.lang.String id,
                              java.lang.String[] channelNames,
                              DataType dataType,
                              double sampleRate)
                              throws DuplicateIdException

Creates a new ValuesEntry in this unisens dataset. A ValuesEntry represents values aquired at certain points in time. A file containing the associated data is also created if not already present. The filename is the same as the id of the Entry.

Parameters:

id - the id of the Entry. Has to be unique within one unisens dataset.

channelNames - an Array of names of the channels. At least on channel has to be present.

dataType - the DataType of the data contained in this SignalEntry.

sampleRate - the sampleRate of the data in samples per second. Points in time are given as sample counts

Returns:

the created ValuesEntry

Throws:

DuplicateIdException

createCustomEntry

CustomEntry createCustomEntry(java.lang.String id)
                              throws DuplicateIdException

Creates a new CumstomEntry in this unisens dataset. This method can be used to add an Entry to this unsiens dataset that is not specified by the unisens specification.

Parameters:

id - the id of the Entry. Has to be unique within one unisens dataset.

Returns:

the created CustomEntry

Throws:

DuplicateIdException

closeAll

void closeAll()

Closes all open Entries contained in this unisens dataset

addEntry

Entry addEntry(Entry entry,
               boolean deepCopy)
               throws DuplicateIdException

Add an existing Entry to this unisens dataset. This method can be used to copy an existing Entry to this unsiens dataset. If deepCopy=true also the corresponding data file will be copied.

Parameters:

entry - the entry that should be added.

deepCopy - flag that indicates to copy the datafile

Returns:

the added Entry

Throws:

DuplicateIdException

addGroup

Group addGroup(Group group,
               boolean deepCopy)
               throws DuplicateIdException

Add an existing Group and its Entries to this unisens dataset. This method can be used to copy an existing Group and its Entries to this unsiens dataset. If deepCopy=true also the corresponding data files will be copied.

Parameters:

group - the group that should be added.

deepCopy - flag that indicates to also copy the datafiles

Returns:

the added Group

Throws:

DuplicateIdException

getCustomAttributes

java.util.HashMap<java.lang.String,java.lang.String> getCustomAttributes()

Returns the custom attributes of this unisens dataset. Custom attributes can be used to add simple context information as key/values pairs. For complex context information createContext(String schemaUrl) should be preferred.

Returns:

all custom attribues as HashMap

addCustomAttribute

void addCustomAttribute(java.lang.String key,
                        java.lang.String value)

Add a ned custom attributes to this unisens dataset. Custom attributes can be used to add simple context information as key/values pairs. For complex context information createContext(String schemaUrl) should be preferred.

Parameters:

key - the key of the new attribute

value - the value of the new attribute