|This page describes the development and use of Resource objects and associations in ION Release 2, for information persistence. This guide is based on the R2 container use guide and the R2 service implementation guide.|
Resources are persistent data objects with unique identity in the system and with an associated life cycle workflow. A resource has a Resource Type that determines the definition of the resource object. Every Resource instance (Resource for short) is an object of the Resource Type. All fields have a default value that is set, if no specific value was provided on write. Resources are manipulated via the Resource Registry.
The Resource Registry takes the role of a database in the ION system. To make an analogy with a relational database system: Think of different resource types as different "tables" in the database. Resource instances (objects) are the rows in these tables and their columns are the fields as defined in the resource definition. In contrast to static relational schemas, Resource objects support nested structures with arbitrary number of fields. The object's unique identifier is the primary key for the row.
Resources can have associations of defined type to other resources, in form of association triples (similar to RDF): subject-resource-id, predicate, object-resource-id. For instance the Platform resource defines several "hasInstrument" associations to Instrument resources.
All Resources follow a life cycle defined for the Resource Type. This is the workflow the resource goes through from cradle to grave. Different actions are permitted in different states of this workflow (e.g. usage by non-owners is only permitted in the ACTIVE state).
Resources should be modified only by the service that is responsible for it. Resources can be read by related services.
See also the following architecture pages:
Resources are conceptualized and detailed on the R2 Resource Definition pages.
|The need for a specific concept to be represented as a resource in ION, and its specific name is determined by the architecture team. Please contact an architect for more questions.|
Resource Types are defined as objects in YAML object definition files. in the "ion-definitions" repository, "objects/data" subdirectory, and below.
|The "ion-definitions" repository realizes the central contract between system entities. Write access to this repository is currently limited to architects only. However, you may use an own fork of ion-definitions for testing out local changes and submit pull requests with changes for the master branch in ooici.|
Resource Type objects must extend Resource. Use the "!Extends_" tag in YAML to include the standard Resource fields into the resource definition. (The '!' notation is YAML, but 'Extends_' is an OOI CI construct.)
|Resources MUST extend Resource or one of its subtypes (InformationResource, TaskableResource) in order to be identified as Resource objects.|
The following fields exist for every resource:
| Field Name
|| READ ONLY
|| The unique identifier of a resource. Is set by the framework on create and must remain unchanged on update.
||READ ONLY|| The revision identifier for a resource instance. This is used to detect concurrent updates. In this case 2 updates are based on the same resource read, the more recent of the updates will fail and has to mitigate.
||READ ONLY|| The type name of the object as str, e.g. "Instrument"
|| The identifying, human readable name of the resource. This is the name a resource would appear in a user interface table of resources
|| A more verbose description of the resource's purpose.
||READ ONLY|| The life cycle state of the resource
|| READ ONLY
|| Timestamp when resource object was created (set by the framework); in millis
|| READ ONLY
||Timestamp when resource object was updated (set by the framework); in millis|
|Do not attempt to redefine these field in a resource definition. Do not add fields that have a similar meaning (e.g. "ID", "resource_name" etc). The strength of the framework lays in the uniform treatment of all resources.|
Similar to relational database schemas, there exist relationships between the entities in the logical model (see Entity-Relationship modeling). In ION, the entities are the Resources (types) and the relationships are the associations. In relational databases, most of the relationships are expressed as primary-foreign key relations, i.e. in one table row, the foreign key of another table's row is specified and the database provides for referential integrity (e.g. cascading delete etc).
In ION, all associations are first class entities. Resource objects do not contain the ID's of other Resources to provide a reference. Instead, an Association object is created that contains the ID's of a subject (i.e. source) and an object (i.e. destination) Resource as well as an Association Type, which is called the predicate. This subject-predicate-object model follows the ideas of RDF triples, used in semantics applications.
Association Types and constraints are defined in the "ion-definitions" repository, in the file "res/config/associations.yml". This file defines the list of Association Types with permitted subject Resource Types (domain) and permitted object Resource Types (range). The Resource Registry will enforce these constants when associations are created. Note that base types, such as Resource, are allowed as well.
Resources should be read and updated only from the service that is primarily responsible for the Resource Type.
Create a resource object in memory and resource registry
Create a resource in a service with contents coming in request
Create a resource and associate with other resource
Associate two resource objects
|Creating associations means relating the HEAD revision of both associations. Associations to specific revisions are not yet supported.|
Update a resource in a service
|Be aware that you cannot create and update an IonObject subsequently without reading first. Create has a consequence in the resource registry layer (_id and _rev fields) that is not reflected back into the IonObject.|
All resources follow the life cycle workflow defined for the resource type. The Resource Registry service is responsible for advancing resource life cycle.
The following find operations are supported by the Resource Registry. They are based on efficient indexing of the resources and their associations. These operations all return tuples. The first element is either a list of resource IDs, or a list of resource objects. The second element is a list of matching associations.
All find operations support flexible parameters. Parameters have to be provided left to right. You can choose to leave more right-most parameters as None, in order to return a broader result set.
Resource Types, Association Types and Life Cycle States are provided by importing the following:
The main find operation based on resource attributes is find_resources(restype, lcstate, name, id_only)
Find Resource by association: Subject to Object
Find Resource by association: Object to Subject
|View and manipulate the CouchDB datastore, by accessing http://localhost:5984/_utils.|