Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • caosdb/src/caosdb-server
1 result
Show changes
Commits on Source (33)
Hide whitespace changes
Inline Side-by-side
Showing
with 535 additions and 234 deletions
.gitignore
View file @ e2320592
......@@ -38,3 +38,4 @@ authtoken/
# python
__pycache__
*~
CHANGELOG.md
View file @ e2320592
......@@ -9,6 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
### Changed
### Deprecated
### Removed
### Fixed
- #145 Documentation of importances and inheritance
### Security
## [v0.4.0] - 2021-06-21
### Added
* Related to #146, a new flag for entities and complete transactions:
`force-missing-obligatory=[ignore|warn|error]`. The flag overrides the
default behavior of the server (throwing an error when an obligatory property
is missing). `ignore` just discards the consistency check, `warn` only issues
a warning when obligatory properties are missing and `error` throws an error
in that case. The flag can be set for the complete transaction and each
single entity, while the entity flag takes precedence.
* New EntityState plug-in. The plug-in disabled by default and can be enabled
by setting the server property `EXT_ENTITY_STATE=ENABLED`. See
[!62](https://gitlab.com/caosdb/caosdb-server/-/merge_requests/62) for more
......@@ -25,12 +48,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Changed
* The default session timeout changed from 10 min to 60 min. Please set it to
your needs via the server config option `SESSION_TIMEOUT_MS`.
### Deprecated
### Removed
### Fixed
* #146 - Default behavior for missing obligatory properties
* #131 - CQL Parsing error when white space characters before some units.
* #134 - CQL Parsing error when multiple white space characters after `FROM`.
* #130 - Error during `FIND ENTITY` when
......
DEPENDENCIES.md
View file @ e2320592
* caosdb-mysqlbackend == 4.0.0
* caosdb-mysqlbackend == 4.1.0
* Java 11
* Apache Maven >= 3.6.0
* make >= 4.2.0
......
README_SETUP.md
View file @ e2320592
......@@ -80,7 +80,7 @@ server:
Replace `localhost` by your host name, if you want.
- `keytool -importkeystore -srckeystore caosdb.jks -destkeystore caosdb.p12 -deststoretype PKCS12 -srcalias selfsigned`
- Export the public part only: `openssl pkcs12 -in caosdb.p12 -nokeys -out cert.pem`.
The resulting `cert.pem` can safely be given to users to allow ssl verification.
The resulting `cert.pem` can safely be given to users to allow ssl verification.
- You can check the content of the certificate with `openssl x509 -in cert.pem -text`
Alternatively, you can create a keystore from certificate files that you already have:
......@@ -93,14 +93,14 @@ server:
appropriately:
* Setup for MySQL back-end:
specify the fields `MYSQL_USER_NAME`, `MYSQL_USER_PASSWORD`,
`MYSQL_DATABASE_NAME`, and `MYSQL_HOST`.
`MYSQL_DATABASE_NAME`, and `MYSQL_HOST`.
* Choose the ports under which CaosDB will be accessible.
* Setup the SSL certificate: Assuming that there is an appropriate `Java Key
Store` file (see above), change the fields `CERTIFICATES_KEY_PASSWORD`,
`CERTIFICATES_KEY_STORE_PATH`, and `CERTIFICATES_KEY_STORE_PASSWORD`.
Make sure that the conf file is not readable by other users because the
certificate passwords are stored in plaintext.
- Set the path to the authtoken config (see step 4)
- Set the path to the authtoken config (see step 4)
* Set the file system paths:
- `FILE_SYSTEM_ROOT`: The root for all the files managed by CaosDB.
- `DROP_OFF_BOX`: Files can be put here for insertion into CaosDB.
......@@ -121,7 +121,7 @@ server:
* See also [README_CONFIGURATION.md](README_CONFIGURATION.md)
6. Copy `conf/core/usersources.ini.template` to `conf/ext/usersources.ini`.
* You can skip this if you do not want to use an external authentication.
Local users (CaosDB realm) are always available.
Local users (CaosDB realm) are always available.
* Define the users/groups who you want to include/exclude.
* Assign at least one user the `administration` role.
* For example, if the admin user is called `caosdb`, there should be the
......
caosdb-webui @ c2dc8e9e
Subproject commit 5dfe879722bd01acc5209c581b60bf0ac49635b6
Subproject commit c2dc8e9e9e0517ee7fb0d280717211a015906f64
conf/core/jobs.csv 0 → 100644
View file @ e2320592
#
# This file is a part of the CaosDB Project.
#
# Copyright (C) 2021 Timm Fitsche <t.fitschen@indiscale.com>
# Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU Affero General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU Affero General Public License for more details.
#
# You should have received a copy of the GNU Affero General Public License
# along with this program. If not, see <https://www.gnu.org/licenses/>.
#
# Five columns:
# DOMAIN_ID, ENTITY_ID, TRANSACTION, JOB, JOB_FAILURE_SEVERITY
# general rules
0,0,INSERT,CheckPropValid,ERROR
0,0,INSERT,CheckParValid,ERROR
0,0,INSERT,CheckParOblPropPresent,ERROR
0,0,INSERT,CheckValueParsable,ERROR
0,0,UPDATE,CheckPropValid,ERROR
0,0,UPDATE,CheckParValid,ERROR
0,0,UPDATE,CheckParOblPropPresent,ERROR
0,0,UPDATE,CheckValueParsable,ERROR
0,0,DELETE,CheckReferenceDependencyExistent,ERROR
0,0,DELETE,CheckChildDependencyExistent,ERROR
# role specific rules
## recordtype rules
0,1,INSERT,CheckNamePresent,ERROR
0,1,INSERT,CheckPropPresent,WARN
0,1,INSERT,SetImpToRecByDefault,ERROR
0,1,UPDATE,CheckNamePresent,ERROR
0,1,UPDATE,CheckPropPresent,WARN
0,1,UPDATE,SetImpToRecByDefault,ERROR
## record rules
0,2,INSERT,CheckNamePresent,WARN
0,2,INSERT,CheckPropPresent,WARN
0,2,INSERT,CheckParPresent,ERROR
0,2,INSERT,SetImpToFix,ERROR
0,2,UPDATE,CheckNamePresent,WARN
0,2,UPDATE,CheckPropPresent,WARN
0,2,UPDATE,CheckParPresent,ERROR
0,2,UPDATE,SetImpToFix,ERROR
## file rules
0,3,INSERT,CheckNamePresent,WARN
0,3,INSERT,MatchFileProp,ERROR
0,3,INSERT,CheckTargetPathValid,ERROR
0,3,INSERT,SetImpToFix,ERROR
0,3,UPDATE,CheckNamePresent,WARN
0,3,UPDATE,MatchFileProp,ERROR
0,3,UPDATE,CheckTargetPathValid,ERROR
0,3,UPDATE,SetImpToFix,ERROR
## property rules
0,4,INSERT,CheckDatatypePresent,ERROR
0,4,UPDATE,CheckDatatypePresent,ERROR
0,4,INSERT,CheckNamePresent,ERROR
0,4,UPDATE,CheckNamePresent,ERROR
0,4,INSERT,SetImpToFix,ERROR
0,4,UPDATE,SetImpToFix,ERROR
## query template rules
0,8,UPDATE,CheckQueryTemplate,ERROR
0,8,INSERT,CheckQueryTemplate,ERROR
# data type specific rules
## reference rules
0,11,INSERT,CheckRefidPresent,WARN
0,11,INSERT,CheckRefidValid,ERROR
0,11,INSERT,CheckRefidIsaParRefid,WARN
0,11,UPDATE,CheckRefidPresent,WARN
0,11,UPDATE,CheckRefidValid,ERROR
0,11,UPDATE,CheckRefidIsaParRefid,WARN
## integer rules
0,12,INSERT,CheckUnitPresent,WARN
0,12,INSERT,ParseUnit,WARN
0,12,UPDATE,CheckUnitPresent,WARN
0,12,UPDATE,ParseUnit,WARN
## double rules
0,13,INSERT,CheckUnitPresent,WARN
0,13,INSERT,ParseUnit,WARN
0,13,UPDATE,CheckUnitPresent,WARN
0,13,UPDATE,ParseUnit,WARN
## filereference rules
0,17,INSERT,CheckRefidValid,ERROR
0,17,INSERT,CheckRefidIsaParRefid,ERROR
0,17,UPDATE,CheckRefidValid,ERROR
0,17,UPDATE,CheckRefidIsaParRefid,ERROR
conf/core/server.conf
View file @ e2320592
......@@ -68,7 +68,7 @@ MYSQL_USER_NAME=caosdb
# Password for the user
MYSQL_USER_PASSWORD=caosdb
# Schema of mysql procedures and tables which is required by this CaosDB instance
MYSQL_SCHEMA_VERSION=v4.0.0
MYSQL_SCHEMA_VERSION=v5.0
# --------------------------------------------------
......@@ -124,6 +124,9 @@ ONE_TIME_TOKEN_EXPIRES_MS=604800000
# Path to config file for one time tokens, see authtoken.example.yml.
AUTHTOKEN_CONFIG=
# Path to config file for the job rules (e.g. which job is loaded for which kind of entity)
JOB_RULES_CONFIG=conf/core/jobs.csv
# Timeout after which a one-time token expires once it has been first consumed,
# regardless of the maximum of replays that are allowed for that token. This is
# only a default value. The actual timeout of tokens can be configured
......@@ -190,9 +193,5 @@ GLOBAL_ENTITY_PERMISSIONS_FILE=./conf/core/global_entity_permissions.xml
ENTITY_VERSIONING_ENABLED=true
# --------------------------------------------------
# Extension settings
# --------------------------------------------------
# Enabling the state machine extension
# EXT_STATE_ENTITY=ENABLE
pom.xml
View file @ e2320592
......@@ -25,7 +25,7 @@
<modelVersion>4.0.0</modelVersion>
<groupId>org.caosdb</groupId>
<artifactId>caosdb-server</artifactId>
<version>0.4.0-SNAPSHOT</version>
<version>0.5.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>CaosDB Server</name>
<properties>
......
src/doc/Data-Model.md
View file @ e2320592
# CaosDB Data Model
The data structure is build from some basic building blocks which are shown in the following picture:
The data structure is built from some basic building blocks which are
shown in the following picture:
![entities](entities.png)
It has a base object called **Entity**. Entities are either **Record Types**, **Records**, or **Abstract
Properties** (and Record like objects for files).
What *kind of data* is stored is defined by the Record Types. Actual data is then stored in CaosDB as Records which are of some Record Type. Those Records can have Properties that contain information about the Record. The following is a more detailed explanation (also see this [paper](https://www.mdpi.com/2306-5729/4/2/83)).
> Record Types and Abstract Properties are used to define the ontology for a particular
> domain in which the RDMS is used. Records are used to store the actual data and therefore
> represent individuals or particular things, e.g. a particular experiment, a particular time series, etc.
**Record Types** define classes or types of things, e.g. persons, experiments, timeseries, etc. Records
can be viewed as members of the class defined by its Record Type. These classes can contain
Abstract Properties which define key-value relationships for properties of the things along
with the expected data type and possibly the default unit, a default value, or a range of permitted
values. As files on the back-end file system are a major focus of this database management system,
there is a special entity File that encapsulates typical file properties like path, size and checksum.
**Entities** can be related via binary, directed, transitive is-a relations which model both subtyping
and instantiation, depending on the relata. These relations construct a directed graph of the
Entities. If A is-a B we call A the child of B and B the parent of A. No adamant restrictions are
imposed on the relate of the is-a relation and thus, Entities can be children of multiple Entities.
Each Entity has a list of Entity Properties, or in short just **Properties**. An Entity Property is not an Entity of its own, but a triple of an Abstract Property, a value or Null, and
an Importance. The values can be numericals, strings, dates, any other valid value that fits into
one of several builtin data types, or, most notably, references to other Entities. The importance
is either obligatory, recommended, suggested, or fix. A valid child of an Entity implicitly
inherits its parent’s Properties according to their Importance, which means that it is obliged,
recommended or only suggested to have a Property with the same Abstract Property (or
any subtype thereof).
As opposed to Properties with other priorities, **Fixed Properties** have no effect on the Entity’s children. During the creation or update of Entities, the importances of the parents are
being checked by the Server. Missing obligatory Properties invalidate the transaction and
result in an error, by default. Missing Properties, when they are recommended, result in a
warning, but the transaction is considered valid. Entities with missing suggested Properties
are silently accepted as valid.
It has a base object called **Entity**. Entities are either **Record
Types**, **Records**, or **Abstract Properties** (and Record like
objects for files). What *kind of data* is stored is defined by the
Record Types. Actual data is then stored in CaosDB as Records which
are of some Record Type. Those Records can have Properties that
contain information about the Record. The following is a more detailed
explanation (also see this
[paper](https://www.mdpi.com/2306-5729/4/2/83)).
> Record Types and Abstract Properties are used to define the ontology
> for a particular domain in which the RDMS is used. Records are used
> to store the actual data and therefore represent individuals or
> particular things, e.g. a particular experiment, a particular time
> series, etc.
## Record Types
**Record Types** define classes or types of things, e.g. persons,
experiments, timeseries, etc. Records can be viewed as members of the
class defined by its Record Type. These classes can contain Abstract
Properties which define key-value relationships for properties of the
things along with the expected data type and possibly the default
unit, a default value, or a range of permitted values. As files on the
backend file system are a major focus of this database management
system, there is a special File entity that encapsulates typical file
properties like path, size and checksum.
## Entities
**Entities** can be related via binary, directed, transitive is-a
relations which model both subtyping and instantiation, depending on
the relata. These relations construct a directed graph of the
Entities. If A is-a B we call A the child of B and B the parent of
A. No adamant restrictions are imposed on the relate of the is-a
relation and thus, Entities can be children of multiple Entities.
## Properties
Each Entity has a list of Entity Properties, or in short just
**Properties**. An Entity Property is not an Entity of its own, but a
triple of an Abstract Property, a value or Null, and an
Importance. The values can be numerals, strings, dates, any other
valid value that fits into one of several builtin data types, or, most
notably, references to other Entities. The Importance is either
`obligatory`, `recommended`, `suggested`, or `fix`. A valid child of
an Entity implicitly inherits its parent’s Properties according to
their Importance, which means that it is obliged, recommended or only
suggested to have a Property with the same Abstract Property (or any
subtype thereof). As opposed to Properties with other priorities,
**Fixed Properties** have no effect on the Entity’s children.
During the creation or update of Entities, the importances of the
parents are checked by the server. Missing obligatory Properties
invalidate the transaction and result in an error, by default. Missing
Properties, when they are recommended, result in a warning, but the
transaction is considered valid. Entities with missing suggested
Properties are silently accepted as valid. See [the detailed
specification of RecordTypes](specification/RecordType) for more
information on importances and inheritance.
src/doc/Glossary.md
View file @ e2320592
# Glossary
## Valid ID
The ID of an existing entity. It is by definition unique among the IDs of all existing entities and is a positive integer."
## Valid Unique Existing Name
A name of an exiting entity which is unique among the names of all existing entities.
......@@ -8,10 +12,6 @@ A name of an exiting entity which is unique among the names of all existing enti
A name of a to-be-inserted/updated entity _e_ which is unique among the names of all other entities that are to be inserted or updated along with the entity _e_.
## Valid ID
The ID of an existing entity. It is by definition unique among the IDs of all existing entities and is a positive integer."
## Valid Unique Temporary ID
The negative integer ID of a to-be-inserted entity _e_ which is unique among the ids of all other entities that are to be inserted along with the entity _e_.
src/doc/_static/css/server_docu.css 0 → 100644
View file @ e2320592
table, .wy-table-responsive table {
border-collapse: collapse;
table-layout: fixed;
}
table td, .wy-table-responsive table td {
word-wrap: break-word;
white-space: unset;
}
src/doc/concepts.rst
View file @ e2320592
......@@ -7,7 +7,7 @@ Basic concepts of the CaosDB server
:glob:
Data Model <Data-Model>
Permissions
permissions
roles
The CaosDB server provides the HTTP API resources to users and client libraries. It uses a plain
......
src/doc/conf.py
View file @ e2320592
......@@ -25,9 +25,9 @@ copyright = '2020, IndiScale GmbH'
author = 'Daniel Hornung'
# The short X.Y version
version = '0.3'
version = '0.5'
# The full version, including alpha/beta/rc tags
release = '0.3'
release = '0.5.0-SNAPSHOT'
# -- General configuration ---------------------------------------------------
......@@ -94,7 +94,13 @@ html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
# html_static_path = ['_static']
html_static_path = ['_static']
# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
'css/server_docu.css',
]
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
......
src/doc/Permissions.rst → src/doc/permissions.rst
View file @ e2320592
......@@ -60,7 +60,7 @@ Possible actions
Until it is completely added to this documentation, a detailed
description of the actions governed by these permissions can be found
`in the
sources <https://gitlab.com/caosdb/caosdb-server/blob/dev/src/main/java/caosdb/server/permissions/EntityPermission.java#L119>`__.
sources <https://gitlab.com/caosdb/caosdb-server/-/blob/dev/src/main/java/org/caosdb/server/permissions/EntityPermission.java#L119>`__.
Typical permissions are:
......
src/doc/specification/AbstractProperty.md
View file @ e2320592
.. note ::
# Note #
This document has not been updated for a long time. Although it is concerned with the mostly
stable API, its content may no longer reflect the actual CaosDB behavior.
> This document has not been updated for a long time. Although it is concerned with the mostly
> stable API, its content may no longer reflect the actual CaosDB behavior.
# AbstractProperty Specification
**Warning:** This specification is outdated. It is included to serve as a starting point for a more up-to-date description of the `Property` entity.
## Introduction
An `AbstractProperty` is one of the basal objects of HeartDB.
An `AbstractProperty` is one of the basal objects of CaosDB.
An `AbstractProperty` MUST have the following _qualities_ (shortcut in brackets):
* a persistent id (`id`)
* an unique name (`name`)
......@@ -39,7 +41,7 @@ An `AbstractProperty` is represented in xml by a `<Property/>` tag. It's _qualit
Depending on the purpose of the xml document (shall it represent an object in the database or an object _to be posted _to the database?) the `<Property/>` tag may actually have just a few of the mentioned "quality-attributes".
### GET AbstractProperty
Any xml representation of an `AbstractProperty` that is retrieved from the HeartDB Server MUST have exactly ONE of the following forms, depending on the `AbstractProperty's` type:
Any xml representation of an `AbstractProperty` that is retrieved from the CaosDB Server MUST have exactly ONE of the following forms, depending on the `AbstractProperty's` type:
#### text
<Property id="$id" name="$name" description="$description" generator="$generator" creator="$creator" created="$created" type="text" />
......@@ -59,10 +61,10 @@ Any xml representation of an `AbstractProperty` that is retrieved from the Heart
<Property id="$id" name="$name" description="$description" generator="$generator" creator="$creator" created="$created" type="file" />
'''General Notes:
* If the called Property does not exist or if the Property called without permission, the HeartDB Server will return an Error.
* If the called Property does not exist or if the Property called without permission, the CaosDB Server will return an Error.
### POST AbstractProperty
Any xml representation of an `AbstractProperty` that is to be posted to the HeartDB server MUST have exactly ONE of the following forms, depending on the `AbstractProperty's` type:
Any xml representation of an `AbstractProperty` that is to be posted to the CaosDB server MUST have exactly ONE of the following forms, depending on the `AbstractProperty's` type:
#### text
<Property name="$name" description="$description" generator="$generator" type="text" />
......@@ -82,10 +84,10 @@ Any xml representation of an `AbstractProperty` that is to be posted to the Hear
<Property name="$name" description="$description" generator="$generator" type="file" />
*General Notes:*
* The `AbstractProperty's` `id` and timestamp (`created`) will be generated by the HeartDB Server.
* The `AbstractProperty's` creator will be determined by the HeartDB Server depending on it's policy configuration.
* The `AbstractProperty's` `id` and timestamp (`created`) will be generated by the CaosDB Server.
* The `AbstractProperty's` creator will be determined by the CaosDB Server depending on it's policy configuration.
* Any given attribute beyond these will be *ignored*.
* If the `<Property/>` tag isn't compliant with these the HeartDB Server will return an Error.
* If the `<Property/>` tag isn't compliant with these the CaosDB Server will return an Error.
----
## Examples
......
src/doc/specification/Authentication.md
View file @ e2320592
# Authentication
Some features of HeartDB are available to registered users only. Making any changes to the data stock via HTTP requires authentication by `username` _plus_ `password`. They are to be send as a HTTP header, while the password is to be hashed by the sha512 algorithm:
Some features of CaosDB are available to registered users only. Making any changes to the data stock via HTTP requires authentication by `username` _plus_ `password`. They are to be send as a HTTP header, while the password is to be hashed by the sha512 algorithm:
| `username:` | `$username` |
|-------------|-------------|-
......
src/doc/specification/Fileserver.md
View file @ e2320592
# Fileserver
## Info
There are several ways to utilize the file server component of HeartDB. It is possible to upload a file or a whole folder including subfolders via HTTP and the _drop off box_. It is possible to download a file via HTTP identified by its ID or by its path in the internal file system. Furthermore, it is possible to get the files metadata via HTTP as an xml.
There are several ways to utilize the file server component of CaosDB. It is possible to upload a file or a whole folder including subfolders via HTTP and the _drop off box_. It is possible to download a file via HTTP identified by its ID or by its path in the internal file system. Furthermore, it is possible to get the files metadata via HTTP as an xml.
## File upload
### Drop off box
The drop off box is a directory on the HeartDB server's local file system, specified in the `server.conf` file in the server's basepath (something like `~/HeartDB/server/server.conf`). The key in the `server.conf` is called `dropoffbox`. Since the drop off box directory is writable for all, users can push their files or complete folders via a `mv` or a `cp` (recommended!) in that folder. The server deletes files older than their maximum lifetime (24 hours by default, specified `in server.conf`). But within their lifetime a user can prompt the server to pick up the file (or folder) from the drop off box in order to transfer it to the internal file system.
The drop off box is a directory on the CaosDB server's local file system, specified in the `server.conf` file in the server's basepath (something like `~/CaosDB/server/server.conf`). The key in the `server.conf` is called `dropoffbox`. Since the drop off box directory is writable for all, users can push their files or complete folders via a `mv` or a `cp` (recommended!) in that folder. The server deletes files older than their maximum lifetime (24 hours by default, specified `in server.conf`). But within their lifetime a user can prompt the server to pick up the file (or folder) from the drop off box in order to transfer it to the internal file system.
Now, the user may send a pick up request to `POST http://host:port/mpidsserver/FilesDropOff` with a similar body:
......@@ -38,9 +38,9 @@ where
There is an example on file upload using cURL described in detail in [the curl section of this
documentation](../administration/curl-access.md).
File upload via HTTP is implemented in a [rfc1867](http://www.ietf.org/rfc/rfc1867.txt) consistent way. This is a de-facto standard that defines a file upload as a part of an HTML form submission. This concept shall not be amplified here. But it has to be noticed that this protocol is not designed for uploads of complete structured folders. Therefore the HeartDB file components have to impose that structure on the upload protocol.
File upload via HTTP is implemented in a [rfc1867](http://www.ietf.org/rfc/rfc1867.txt) consistent way. This is a de-facto standard that defines a file upload as a part of an HTML form submission. This concept shall not be amplified here. But it has to be noticed that this protocol is not designed for uploads of complete structured folders. Therefore the CaosDB file components have to impose that structure on the upload protocol.
HeartDB's file upload resource does exclusively accept POST requests of MIME media type `multipart/form-data`. The first part of each POST body is expected to be a form-data text field, containing information about the files to be uploaded. It has to meet the following requirements:
CaosDB's file upload resource does exclusively accept POST requests of MIME media type `multipart/form-data`. The first part of each POST body is expected to be a form-data text field, containing information about the files to be uploaded. It has to meet the following requirements:
* `Content-type: text/plain; charset=UTF-8`
* `Content-disposition: form-data; name="FileRepresentation"`
......
src/doc/specification/Record.md
View file @ e2320592
# Record
**Warning:** This specification is outdated. It is included to serve as a starting point for a more up-to-date description of the `Record` entity.
= GET records =
......
src/doc/specification/RecordType.md deleted 100644 → 0
View file @ 03d912a7
# RecordType
## Overview
RecordTypes function as templates for [[Record|Records]], they provide a description for a type of Record and define which [[Property|Properties]] should be present. Properties come with an _importance_ attribute which tells the user or client program how strongly necessary the Property is. (As all other entities,) RecordTypes can be inherited from other RecordTypes (or any Entities). When RecordTypes inherit from other RecordTypes, the _inheritance_ flag tells which properties shall be inherited.
### Importance
Importances are more of a recommendation, Records with omitted Properties can technically still be committed.
| *Importance* | *Meaning* | *Consequence when omitted* |
|--------------|----------------------|----------------------------|
| `OBLIGATORY` | Property must be present | *FIXME* Can be forced to be committed the server, but usually an error will be returned. |
| `RECOMMENDED` | Property should be present (makes sense for most users) | *FIXME* Usually an error will be returned? |
| `SUGGESTED` (*FIXME* the default?) | Property may be present (may make sense for some users) | *FIXME* No negative consequence? |
*FIXME* Did I get recommended and suggested right?
### Inheritance
The _inheritance_ flag decides which [[Property|Properties]] are inherited from parents.
| *Inheritance* | *Meaning* |
|----------------|-----------|
| _None_ (default) | Nothing is being inherited |
| `OBLIGATORY` | *FIXME* Properteis of importance `OBLIGATORY` and above? |
| `SUGGESTED` | *FIXME* Properteis of importance `SIGGESTED` and above, so the same effect as `ALL`? |
| `ALL` | Copy everything from the parent. |
| `FIX` | *FIXME* in `tests/test_inheritance.py` of pyint_test this is used, what does it mean???|
## Examples
### GET Requests
#### Single-Get
*Request:*
GET http://localhost:8122/mpidsserver/RecordType/1
*Response:*
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="1" name="Experiment" description="Description Experiment">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="obligatory" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="obligatory" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="suggested" />
</RecordType>
</Response>
----
#### Multi-Get
*Request:*
GET http://localhost:8122/mpidsserver/RecordType/1&2&3
*Response:*
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="1" name="Experiment" description="Description Experiment">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="obligatory" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="obligatory" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="suggested" />
</RecordType>
<RecordType id="2" name="Measurement" description="Description Measurement">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="obligatory" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="obligatory" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="suggested" />
</RecordType>
<RecordType id="3" name="Video" description="Description Video">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="obligatory" />
</RecordType>
</Response>
----
#### Get all
*Request:*
GET http://localhost:8122/mpidsserver/RecordType/
GET http://localhost:8122/mpidsserver/RecordType
*Response:*
<?xml version="1.0" encoding="UTF-8"?>
<Response />
[View Ticket #2](http://dev.bmp.ds.mpg.de/heartdb/ticket/2)
----
### POST Requests
*Request is to be send to:*
POST http://localhost:8122/mpidsserver/RecordType/
POST http://localhost:8122/mpidsserver/RecordType/
----
#### Single-Post
*HTTP Body:*
<Post>
<RecordType name="TimmsRecordType11" >
<Property id="3" importance="recommended"/>
<Property id="4" importance="obligatory"/>
<Property name="age" />
</RecordType>
</Post>
*Response:*
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="40" name="TimmsRecordType11">
<Property id="3" name="name" type="text" description="Name" importance="recommended" />
<Property id="4" name="id" type="integer" description="identifier" importance="suggested" />
</RecordType>
</Response>
----
#### Multi-Post
*HTTP Body:*
<Post>
<RecordType name="TimmsRecordType11" >
<Property id="3" importance="recommended"/>
<Property id="4" importance="obligatory"/>
<Property name="age" />
</RecordType>
<RecordType name="TimmsRecordType12" >
<Property id="6" importance="recommended"/>
<Property id="7" importance="obligatory"/>
<Property id="15" />
</RecordType>
</Post>
*Response:*
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="40" name="TimmsRecordType11" description="null">
<Property id="3" name="name" type="text" description="Name" importance="recommended" />
<Property id="4" name="id" type="integer" description="identifier" importance="suggested" />
<Property id="3" name="name" type="text" description="Name" importance="recommended" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="suggested" />
</RecordType>
<RecordType id="41" name="TimmsRecordType12">
<Property id="6" name="startDate" type="datetime" description="start" importance="recommended" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="suggested" />
<Property id="15" name="TimmsIntProperty" type="integer" unit="kg" description="This is TimmsIntProperty" importance="suggested" />
</RecordType>
</Response>
= DELETE RecordTypes =
HTTP-DELETE-requests are to be send to `http://${host}:${port}/mpidsserver/RecordType/...`. Default port is 8123.
*Example*
{{{
DELETE http://${host}:${port}/mpidsserver/RecordType/1&2&3&4
}}}
src/doc/specification/RecordType.rst 0 → 100644
View file @ e2320592
RecordType
==========
Overview
--------
RecordTypes act as templates for :doc:`Records <Record>`. They
provide a description for a type of Record and define which
:doc:`Properties <AbstractProperty>` could, should, or must be
present. Properties come with an `importance` attribute which tells
the user or client program how strongly necessary the Property is. (As
all other entities,) RecordTypes can inherit from other
RecordTypes (or any Entities). When RecordTypes inherit from other
RecordTypes, the `inheritance` flag tells which properties shall be
inherited from the parents to the children.
Importance
~~~~~~~~~~
The `importance` value of a Property states whether it may, should, or
must be present in all children of this Entity. The table below
lists the possible importances, together with the default behavior of
the server when the property is not present in a child.
.. list-table::
:widths: 25 25 50
:width: 100%
:header-rows: 1
* - Importance
- Meaning
- Consequence when omitted
* - ``OBLIGATORY``
- Property must be present
- Can be forced to be committed the server, but usually
an error will be returned.
* - ``RECOMMENDED``
- Property should be present (makes sense for most users)
- No consequence right now, but in future versions a warning will
be returned.
* - ``SUGGESTED`` (default)
- Property may be present (may make sense for some users)
- No negative consequence
* - ``FIX``
- Property is not present in any child
- ---
The default behavior can be overridden for individual transaction by setting the
`force-missing-obligatory` flag to ``ERROR`` (the default), ``WARN``, or ``IGNORE``. These flags
cause a transaction that would result in an entity with a missing `obligatory` property to return an
error, a warning, or to execute without a warning, respectively. The importance value ``FIX`` is
used for properties that are specific to the Entity itself and is explained below.
.. note::
Note that in contrast to RecordTypes, all properties of a
:doc:`Record` have the importance ``FIX`` since in general, even in the
case of a Record having children, its properties are not
inherited.
Inheritance
~~~~~~~~~~~
The `inheritance` flag specifies which :doc:`Properties
<AbstractProperty>` are inherited from the parent RecordType(s) to the
child.
.. list-table::
:widths: 40 60
:header-rows: 1
* - Inheritance
- Meaning
* - `None` (default)
- Nothing is inherited
* - ``OBLIGATORY``
- Properties of importance ``OBLIGATORY`` and above
* - ``RECOMMENDED``
- Properties of importance ``RECOMMENDED`` and above
* - ``SUGGESTED``
- Properties of importance ``SUGGESTED`` and above
* - ``ALL``
- Copy everything from the parent.
Note that inheritance ``ALL`` is essentially the same as ``SUGGESTED``
right now, but this behavior might change in the future. Also note
that properties of importance ``FIX`` are never inherited this
way. This is precisely what this importance level is meant for:
properties that are specific to the parent entity and are not
inherited by default. You can still add this property to the child
manually if you wish, though, but this is not covered by the
automatic inheritance.
.. note::
The behavior of `inheritance` is currently not well-defined if the
child is a :doc:`Record`, not a RecordType.
Examples
--------
.. warning::
The following examples have not been updated in a while and may
serve as a starting point, but are not guaranteed to be fully
applicable to the most recent versions of CaosDB.
GET Requests
~~~~~~~~~~~~
Single-Get
^^^^^^^^^^
*Request:*
.. code-block::
GET http://localhost:8122/RecordType/1
*Response:*
.. code-block:: XML
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="1" name="Experiment" description="Description Experiment">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="obligatory" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="obligatory" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="suggested" />
</RecordType>
</Response>
Multi-Get
^^^^^^^^^
*Request:*
.. code-block::
GET http://localhost:8122/RecordType/1&2&3
*Response:*
.. code-block:: XML
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="1" name="Experiment" description="Description Experiment">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="obligatory" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="obligatory" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="suggested" />
</RecordType>
<RecordType id="2" name="Measurement" description="Description Measurement">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="obligatory" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="obligatory" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="suggested" />
</RecordType>
<RecordType id="3" name="Video" description="Description Video">
<Property id="1" name="explanation" type="text" description="explains the thing" importance="recommended" />
<Property id="6" name="startDate" type="datetime" description="start" importance="recommended" />
<Property id="12" name="file" type="file" description="file" importance="obligatory" />
</RecordType>
</Response>
Get all
^^^^^^^
*Request:*
.. code-block::
GET http://localhost:8122/RecordType/
GET http://localhost:8122/RecordType
*Response:*
.. note::
Outdated? At least the bug tracker doesn't exist anymore.
.. code-block:: XML
<?xml version="1.0" encoding="UTF-8"?>
<Response />
[View Ticket #2](http://caosdb.example.com/caosdb/ticket/2)
POST Requests
~~~~~~~~~~~~~
*Request is to be send to:*
.. code-block::
POST http://localhost:8122/RecordType/
POST http://localhost:8122/RecordType/
Single-Post
^^^^^^^^^^^
*HTTP Body:*
.. code-block:: XML
<Post>
<RecordType name="TimmsRecordType11" >
<Property id="3" importance="recommended"/>
<Property id="4" importance="obligatory"/>
<Property name="age" />
</RecordType>
</Post>
*Response:*
.. code-block:: XML
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="40" name="TimmsRecordType11">
<Property id="3" name="name" type="text" description="Name" importance="recommended" />
<Property id="4" name="id" type="integer" description="identifier" importance="suggested" />
</RecordType>
</Response>
Multi-Post
^^^^^^^^^^
*HTTP Body:*
.. code-block:: XML
<Post>
<RecordType name="TimmsRecordType11" >
<Property id="3" importance="recommended"/>
<Property id="4" importance="obligatory"/>
<Property name="age" />
</RecordType>
<RecordType name="TimmsRecordType12" >
<Property id="6" importance="recommended"/>
<Property id="7" importance="obligatory"/>
<Property id="15" />
</RecordType>
</Post>
*Response:*
.. code-block:: XML
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<RecordType id="40" name="TimmsRecordType11" description="null">
<Property id="3" name="name" type="text" description="Name" importance="recommended" />
<Property id="4" name="id" type="integer" description="identifier" importance="suggested" />
<Property id="3" name="name" type="text" description="Name" importance="recommended" />
<Property id="4" name="id" type="integer" description="identifier" exponent="0" importance="suggested" />
</RecordType>
<RecordType id="41" name="TimmsRecordType12">
<Property id="6" name="startDate" type="datetime" description="start" importance="recommended" />
<Property id="7" name="stopDate" type="datetime" description="stop" importance="suggested" />
<Property id="15" name="TimmsIntProperty" type="integer" unit="kg" description="This is TimmsIntProperty" importance="suggested" />
</RecordType>
</Response>
DELETE RecordTypes
~~~~~~~~~~~~~~~~~~
HTTP-DELETE-requests are to be send to ``http://${host}:${port}/RecordType/...``. Default port is 8123.
*Example*
.. code-block::
DELETE http://${host}:${port}/RecordType/1&2&3&4