The fundamental elements of an Orchestra knowledge space are entities. Entities correspond to things. These things may represent items with a real material or physical existence such as people, places, and machines, or they may represent abstractions such as processes, systems, or relationships among other things. Relationships are knowledge space entities that link other entities together, expressing dependencies or requirements between them. Entities in an Orchestra knowledge space may possess attributes that characterize and distinguish them from others (e.g. name, type, size, location) or capture relationships with others. Entities may also possess methods that define specific operations that may be performed upon them. The Orchestra API provides a uniform method for creating and deleting entities in the knowledge space, affixing attributes, accessing methods, linking entities with other entities, and accessing aggregate information. The Orchestra API places no restrictions on what may be an entity. Rather, what constitutes a valid entity type is controlled by an accompanying ontology associated with the knowledge space. At the API level, Orchestra is ontologically neutral. That is, the API imposes no single fixed ontologic structure upon the entities in the knowledge space. An Orchestra ontology may be rigidly fixed, or it may be real-time extendable. However, in order to prevent invalidation of existing knowledge space contents and avoid confusing, ambiguous interpretations of current entity instantiations, Orchestra imposes the restriction that the ontology cannot be dynamically refactored in a manner that would create conflicting definitions for identical entity types. In addition, the API enforces every entity instance to be uniquely identifiable and distinguishable from all other entities. This is achieved through the use of an EUID.
¶ EUID
An EUID looks like <1000|3|100573>
Permanently associated with every entity is an entity unique identifier (EUID). This identifier is guaranteed to be unique across an entire Orchestra server constellation. An entity's EUID is provided by the Orchestra framework at the moment an entity is created and can never be changed. Every EUID consists of 3 parts:
- Network Identifier (NID) (used to be called Public Identifier (PID), and is still how some codebase call it)
- Host Identifier (HID)
- Unique Identifier (UID)
The NID Identifies the public network where the Orchestra server that is managing the entity resides The HID identifies the specific host within the public network. The UID identifies the entity itself on the designated host.
The combination of NID and HID uniquely identifies the Orchestra server and enables routing through the Orchestra peer-to-peer network. The three components together form a 128-bits identifier. For textual representation, a EUID is displayed as three decimal number groups separated by the '|' (pipe) character enclosed in angle brackets in the form <nid|hid|uid>. Several of the Orchestra tools allow the shorthand forms <hid|uid> and where the missing nid and hid fields default to that of the current server
When an entity is created, the NID and HID are assigned by the server corresponding to the server's public and host network identifiers, respectively, and the UID portion of its EUID is assigned by a server in incremental order starting at 100001. When a server receives an entity request, it examines the NID and the HID to determine if it is responsible for managing that entity (i.e. it is the entity's "owner"). If the entity is managed by the local server, the request is dispatched for local fulfillment, otherwise the server uses the NID and HID to forward the request to the proper remote server destination, through the Orchestra peer-to-peer network.
¶ Redirections
Orchestra EUIDs are designed for efficient routing and are generally not very meaningful nor memorable to a person. As a convention to help organize the Orchestra entity identifier space, entities with UIDs in the range 0..100000 are reserved by each server for entity redirection. Entity redirection is a means of mapping a set of "common" (i.e. well-known) UIDs to actual (and generally not well-known) EUIDs. Every server maintains an entity redirection table for this purpose. When a server receives a reference to an entity with NID = 0, HID = 0, and UID < 1000001, the server looks up the entity’s UID in the redirection table, replacing the reference with the EUID table entry. In this manner, a logical entity UID reference is redirected to an actual entity EUID reference. All common EUIDs are of the form <0|0|uid>. The Orchestra system assigns a specific meaning to many of these reserved EUIDs. For example, Orchestra designates entity <0|0|1> as the "AvesTerra Registry", not unlike a parent directory in many conventional file systems
While entity redirection is very helpful on a single server, the EUID of a common/well-known entity on one server may not be well-known on another server. Consequently, Orchestra provides a means of common entity forwarding. That is, whenever a server receives a request for an entity with an EUID of the form <nid|hid|uid> where the UID is less than 100001 and the NID and HID are remote, the server will forward the entity request in the usual manner to the specified remote server. However, upon arrival, the EUID will be reassigned <0|0|uid>. The remote server will then redirect this new common identifier to the entity’s actual EUID on that server via its local redirection table. Using this scheme entity references on one server can be made to entities on another server without having to know the precise EUID in advance
Lastly, entity <0|0|0> has special significance on every server. Specifically, <0|0|0> refers to the server itself. That is, the server recognizes entity <0|0|0> as a reference to its own instance of the running Orchestra server software. In this manner, applications can examine various aspects of the running server, observe various configuration settings, and make certain configuration requests without the need for additional custom API operations. The server accomplishes this by organizing information about itself consistent with the Orchestra model, Orchestra being the main ontological implementation that uses Orchestra. As a result, the same tools for accessing with conventional entities can be used for accessing the server, provided the requesting application has the appropriate authorization.
sources:
- https://avesterra.georgetown.edu/tech/ - Application Programming Interface (API)
- https://avesterra.georgetown.edu/tech/ - Integration and Application Library (Avial®)
¶ Storing things in entities
¶ Metadata
Everything Orchestra needs to save about an entity to manage it properly is saved in the entity's metadata.
An entity metadata can be displayed throug the avu and look like this:
Entity : <0|0|100033>
Server : <0|0|0>
Name : Geospace Registry
Key : Geospace
Context : AVESTERRA
Category : AVESTERRA
Class : SPACE
State : NULL
Timestamp : 2023-06-23 13:06:19
Activated : FALSE
Armed : FALSE
Active : FALSE
Busy : FALSE
Locked : FALSE
References : 2
Blocking : 0
Pending : 0
Waiting : 0
Adapting : 0
Invoking : 0
Timer : 0
Elapsed : 0
Rendezvous : unknown
Authority : 4329b8a9-7bc5-81ac-8c24-d0a879fd6698
Authorizations : 1
00000000-0000-0000-0000-000000000001 0
Conditions : 0
Attachments : 0
Connections : 1
Outlet: <0|0|40>
Method: NULL
Precedence: NULL
Expiration: 2091-07-11 16:20:26
Subscriptions : 0
Elements : 0
The Rendezvous field is the number of rendez-vous happening in parrallel, it was added when multithreaded distributed rendezvous was implemented.
¶ Different kinds of entities
Strictly speaking, all entities are equal, however, there are recurring patterns
that can be thought of as different kinds of entities.
One notable exception is the Server entity <0>, which is used to configure
the Orchestra server.
¶ Server
The only kind of entity that is actually different.
Here's what a server entity looks like:
In its Orchestra Interchange model, the server holds attribute with special
meanings used as configuration or permanent storage describing the state of
the Orchestra server.
TODO: What is the 'Addressing' part?
TODO: What is Network and Host? I assume it's for HGTP tunneling?
The ROUTING attribute contains all of the Entity redirections of the server.
The TOKEN attribute contains all of the Authorization mapping