User database revised

Contains suggested changes to the User database design and API that are needed for subscription information and possibly other needs. Changes to the original User database description are rendered in bold.

Overview

Design

Database tables

UserTable

U_id	A_id	U_name	U_email	U_password	U_institution	U_telephone	U_session

DataSet

DS_id	U_id	A_id	DS_name

Info

I_id	U_id	DS_id	I_type	I_content

File

DS_id	F_name	F_timestamp	F_size	F_status	F_errurl

The table details are presented below:

UserTable

U_id	Unique user id (autoincremented number). Primary key
A_id	Application id. Many METAMOD applications share the same database. This field has the same value as the APPLICATION_ID in the master_config.txt file.
U_name	User name as given in registration form
U_email	User E-mail address as given in registration form
U_password	User password
U_institution	User institution acronym as given in registration form
U_telephone	User telephone number as given in registration form
U_session	User session id. Random string generated when the user initiate a new interactive session.

The U_session field is used to track the state of an interactive user session. The user may only have one interactive session active at any time. If the user initiate a new session when another session is already active, the old session disappears. If the user tries to continue the old session, an error message will be submitted. This is the same mechanism used in the old (METAMOD 2.3 and earlier) file-based version.

The A_id field connects the user to one of the METAMOD applications that share the same database. If the same person wants to be a user of more than one of these METAMOD applications, she/he must apply for a user account in each application, and the database will contain independent rows in the user table, one for each application.

DataSet

DS_id	Unique dataset id (autoincremented number). Primary key. Not same number as in the Metadata Database
U_id	Identifies the user owning the dataset.
A_id	Application id.
DS_name	Dataset name. Name of dataset as provided by the user. Not the same name as in the corresponding field in the Metadata Database. But the last part of the name found in the Metadata Database field (everything after '/') will correspond to this field.

The combination of the A_id and DS_name fields will provide an alternative unique key that can be used to find a dataset without knowing the owning user.

Info

This table is used to contain various information connected to a dataset and/or a user. Each row has a serial unique identifier (I_id). The row can be connected to a dataset through the DS_id foreign key, and to a user through the U_id foreign key. Note that all Info-rows connected to a dataset is also indirectly connected to the owner of the dataset. This is not explicitly expressed in this table. In cases where values for both U_id and DS_id exist, the U_id will usually point to a user that do not own the dataset.

A type tag (I_type) field tells what kind of information is contained in the row. The value is a short acronym for a limited set of information types. The piece of information is found in the I_content text field.

I_id	Unique id (autoincremented number). Primary key
U_id	Identifiles a user this info-row is connected to. Will be missing (NULL) if the information is not connected to a user
DS_id	Identifiles a dataset this info-row is connected to. Will be missing (NULL) if the information is not connected to a dataset
I_type	Type tag. Short acronym that identifies the information type.
I_content	The text string representing a piece of information. This can be a single entity (unstructured text) or an XML document.

For the time being, the following information types (I_type) will be needed.

Type	Connected to	Description
DSKEY	dataset	Dataset key (also called directory key or dirkey) as provided by the user. Single entity
LOCATION	dataset	Location. Single entity. Absolute path to the directory under which all files belonging to the dataset are found. The files may be found directly in the location directory, or in any subdirectory of the location directory at any level.
CATALOG	dataset	Partial URL to a THREDDS dataset. Single entity. Combined with the file name, this URL can be used to access the content of a file through a TDS server. It can also provide the URL that points to the THREDDS catalog containing the METAMOD dataset.
WMS_URL	dataset	URL to the WMS service that can display data from the dataset. Single entity.
WMS_XML	dataset	XML document that describes available alternatives for displaying the dataset in WMS. For example, the parameters that can be displayed. Each parameter may have a palette (for example “BOXFILL/redblue”) found in a style element in the GetCapabilites document. If no palette is found, a default palette is used for the parameter.
SUBSCRIPTION_XML	dataset and user	XML describing details of a subscription on the dataset set up by the user
Additional information types may be added later, for example to implement projection information:
PROJECTION_XML	dataset	XML document used to represent reprojection information. The document contains, among other things, each projection the user has asked for (“Lat/Long”, “Stereo” etc.). Each projection contains attributes: method, projString, xAxis, yAxis and toDegree.

File

DS_id	Dataset this file belongs to. Part of primary key.
F_name	Local path to file. The full path is given by “LOCATION/F_name” where LOCATION is the dataset LOCATION found in the Info table. Part of primary key.
F_timestamp	Timestamp of last change
F_size	File size (bytes)
F_status	Status (OK or errors)
F_errurl	URL to error report (if errors)

This table is used to display recent changes to the data provider. It will not contain a complete inventory of files in the repository. This table will be purged (rows with old timestamps removed) periodically.

API design

This paragraph defines a set of subroutine/function calls that are used to read and write information to/from the user database. These functions will be implemented in PHP and/or Perl as needed.

The functions are defined as methods in a Userbase class. Inside a Userbase object, there may be a current user and a current dataset. The current user will always own the current dataset. There may also be a current file that will belong to the current dataset.

Open/close functions

Method	Purpose	Parameters
new	Create a new Userbase object and set up a connection to the User database	OUT: Userbase object reference
close	Save any pending changes to the database, and close the connection	None
revert	Revert any changes to the database made by this Userbase object. Close the database connection.	None

User functions

Method	Purpose	Parameters
user_find	Search for an existing user in the database and make him/her the current user.	IN: User E-mail address, application id (A_id).
user_create	Create a new user and make it the current user.	IN: User E-mail address, application id (A_id).
user_set	Set user properties for the current user	IN: Property name (one of 'U_name', 'U_password', 'U_institution', 'U_telephone', 'U_session'), property value
user_get	Get user properties for the current user.	IN: Property name (one of 'U_name', 'U_password', 'U_institution', 'U_telephone', 'U_session'). OUT: property value
user_first	Make the first user in the database the current user.	OUT: TRUE if found, FALSE if no users exist.
user_next	Make the next user in the database the current one.	OUT: TRUE if found, FALSE if already last user.

Dataset functions

Method	Purpose	Parameters
dset_create	Create a new dataset and make it the current dataset. The current user will be the owner of the new dataset.	IN: Dataset name, dataset key.
dset_find	Find a dataset in the database and make it the current dataset. Also make the user that owns the dataset the current user.	IN: Application id, dataset name. OUT: true if the dataset is found, false otherwise.
dset_first	Make the first dataset (owned by the current user) the current dataset	OUT: true if found, false if no such dataset exists.
dset_next	Make the next dataset (owned by the current user) the current dataset.	OUT: true if found, false if already last dataset.

Information functions

Functions for reading and writing rows in the Info table. Uses the concept “current infoset”. The current infoset is a subset of the rows in the Info table given by how the rows are connected to the current user and/or the current dataset. In addition, all rows in the current infoset must represent the same information type (I_type).

Method	Purpose	Parameters
info_set	Define the current infoset	IN: 1. Information type. 2. Keyword that tells how the infoset shall relate to the current user and/or current dataset (values: USER, DATASET, USER_AND_DATASET). OUT: Number of rows (N) in the infoset, or FALSE indicating error.
info_get	Get information from the current infoset.	IN: 1. Index into the infoset (0 to N-1). 2. Optional parameter that tells if the current user or the current dataset should be synchronized with the user/dataset that the retrieved Info row represents. TRUE or FALSE (defaults to FALSE). OUT: Value of I_content field (single entity or XML).
info_put	Add or replace content fields in the current infoset.	IN: 1. Value of I_content field (single entity or XML). 2. Index into the infoset (0 to N-1). If this parameter is missing, a new row in the infoset is created. This row is given the index N, after which N is incremented.

File functions

Method	Purpose	Parameters
file_find	Search for an existing file (owned by the curent dataset) and make it the current file.	IN: File name (F_name). OUT: true if found, false otherwise.
file_create	Create a new file (for the current dataset) and make it the current file.	IN: File name (F_name)
file_set	Set file properties for the current file	IN: Property name (one of 'F_size', 'F_status', 'F_errurl'), property value
file_get	Get file properties for the current file.	IN: Property name (one of F_name', 'F_size', 'F_status', 'F_errurl', 'F_timestamp'). OUT: property value
file_first	Make the first file (in the current dataset) the current file.	OUT: true if found, false if no files exist.
file_next	Make the next file in the database the current one.	OUT: true if found, false if already last file.