Object-Global Mapping or "ORM for globals." Direct Access with the Caché Globals Proxy Framework

Imagine the task: given the GlobalsDB or Caché dataset with their notorious globals; It is necessary to provide means of direct access GlobalsAPI, so that in nodes of a global type “^ n (“ Japan ”,“ Yamato ”) = $ lb (“ R.Keanu ”, 1000)" 0 to n; the second indexes are the names of the ships, also with restrictions. And the values ​​for these indices would be the names of the captains and the number of their subordinates, of course, also with restrictions.

Immediately I will inform you that it is impossible to do this only with GlobalsAPI. Caché GlobalsProxy Framework offers a fast and versatile solution for such tasks. By combining Object-Globals Mapping (OGM) technology with GlobalsAPI methods, it is possible to process global data using objects (proxy classes) representing global nodes in the same way as ORM to relational databases - using objects representing tables.
')
Caché GlobalsProxy Framework main features:

1. Means of creating descriptions of data structures and their limitations (metadata) of the global.
2. Automated data validation.
3. Generating proxy classes based on metadata.
4. CRUD operations on data in the global using proxy classes.

All of this should generally increase the speed of development of software products that imply the use of GlobalsAPI for direct access to the globals of the GlobalsDB and Caché databases.

Problematics

When working with high-performance GlobalsAPI directly with globals, there is no need for metadata for them - this provides the extreme flexibility of data storage and reduces the cost of processor time for validation.

However, the fact that the availability of metadata is not necessary does not negate the fact that they are present in one form or another and, naturally, they must be taken into account. Also, at the moment there are no generally accepted rules for the organization of global metadata, respectively, developers have to invent their own ways of describing data structures, restrictions, semantics, decide where to store all this and how to work with it in the future.

However, even having figured it out, developers will also have to independently validate the data, because GlobalsAPI does not contain methods for processing them with any metadata at all, that is, only using it can lead to a violation of logical integrity.

Software development using GlobalsAPI is inconvenient and difficult, therefore, long and expensive. This can play a crucial role in a situation where it would be possible to sacrifice some of the productivity, but speed up development.

The Caché GlobalsProxy Framework provides the means to create a global description and, based on it, provides data processing using proxy classes while hiding the GlobalsAPI methods and logic of working with global metadata, in particular automating validation. All this, with a relatively insignificant loss of productivity, speeds up development many times over.

Providing global metadata

In order to be able to validate the data and present the nodes of the global proxy classes, the global description is first needed. For its storage is intended a specialized global - meta-global. Thus, data and metadata are stored side by side and accessible using the same API (step towards cross-platform).

For the description of the global version of the specification of the meta-global, which has the following form:
For example:
Create a meta-global "^ nMeta" describing the global "^ n" with data on the naval forces of the countries:
Fill global "^ n" according to the created description:

It can be noted that using this variant of the meta-global specification, the structure, semantics and restrictions on the global indexes and values ​​are uniquely set, as if it is assumed that the global data structure cannot be stored, thereby losing the storage flexibility. So it is in some sense, but it is only within the framework of one meta-global ... Nothing prevents to create several meta-globals for the same global.

Object Global Mapping

Now that we have provided global metadata, according to OGM technology, the nodes of the global tree must be represented by proxy classes. So, from the example above, nodes with semantics (ShipInfo), which store values ​​about ships and are available by three indices, will be presented:

public class ShipInfoProxy { //,    public String Country; public Classification ShipClass; public String Name; //,     public ContactInfo Captain; public Int32 StuffCount; public Double Efficienty; ... } public class ShipInfoProxyKey { //,    public String Country; public Classification ShipClass; public String Name; ... } 

Each proxy class has its own manager, which is designed to provide CRUD operations with data, while hiding the logic of working with global and metadata (in particular, data validation).

The ShipInfoProxy proxy class, in the context of this global, will correspond to the ShipInfoProxyManager <ShipInfoProxy, ShipInfoProxyKey> manager, the general view of which is:

 public class ProxyManager<ProxyT, ProxyKeyT> where ProxyT : class where ProxyKeyT : class { public bool Validate; public ProxyManager(EntityMeta meta, TrueNodeReference globalRef, List<IStructManager> structsManagers = null); public ProxyT Get(ArrayList keys); public ProxyT Get(object key); public ProxyT Get(ProxyKeyT key); public List<ProxyT> GetAll(); public void Delete(ProxyKeyT key); public void Save(ProxyT entity); public List<ProxyT> GetByKeyMask(object key); public List<ProxyT> GetByKeyMask (ProxyKeyT key); } 

Where, captain obvious, as if alluding to us:
void Save (ProxyT entity) - saves or replaces data in the global.
ProxyT Get (ProxyKeyT key) - reads data from the global node by the specified key;
void Delete (ProxyKeyT key) - removes a node from the global by the specified key.
public List <'ProxyT> GetAll () - reads values ​​from all nodes;
But this rotation is a special method of data acquisition, which allows to get data from nodes, without specifying some indices of these nodes:
List <'ProxyT> GetByKeyMask (ProxyKeyT key) - reads data from all global nodes whose indexes correspond to the mask specified by the key.

All global node managers are accessible from a special context class that is responsible for their initialization:

 public class NaviesContext : CacheEXTREMEcontext { public ProxyManager<ManufacturerProxy, ManufacturerProxyKey> ManufacturerManager; public ProxyManager<ShipCounterProxy, ShipCounterProxyKey> ShipCounterManager; public ProxyManager<ShipInfoProxy, ShipInfoProxyKey> ShipInfoManager; public WowsNiceContext(InterSystems.Globals.Connection conn) : base(conn, "nMeta") { this.ManufacturerManager = new ProxyManager<ManufacturerProxy,ManufacturerProxyKey> (base.entitiesMeta[typeof(ManufacturerProxy).Name], base.globalRef, base.structsManagers); ... base.structsManagers.Add(new StructManager<Classification> (base.globalMeta.GetLocalStructs()[0], base.structsManagers)); ... } } 

Caché GlobalsProxy Framework

The Caché GlobalsProxy framework consists of the CacheExtremeProxy.dll dynamic link library and a metadata editor utility. To fully use it, namely to edit the data of the global, you need to do, conditionally, in 3 simple steps:

1. Creating Metadata

You can go the hard way, create metadata from the code, using the specially created GlobalMeta class, and then write them to the meta-global:
And you can go a simple way, create metadata using the attached auxiliary application of the metadata editor:



Yes ... there is still "old school" - the way to create a meta-global using COS.

2. Generation of context and proxy classes

And again, you can go a relatively complicated way - code. Fill in a special class GlobalMeta (can be read from a previously created meta-global) and use a special class generator:
And you can, all the same, use the auxiliary editor application:

3. Connection and initialization

We connect the CecheExtremeProxy.dll library to the project, add the generated file with the context and proxy classes. Next, create connections with the database and use it to initialize the class-context.

four. ???????

5. PROFIT!

Now, metadata is available in the process of writing software code (of course, if the development environment supports InteliSense analogue), which doesn’t hurt that “what and where?” Is stored. Managers hide in themselves all the logic of working with the global and metadata, and, in particular, automatically validate the data. From all this, you can almost forget that direct access is used.

Examples of using

Next, you need to initialize the context:

 //    - NaviesContext Navies = new NaviesContext(conn); 

Suppose we want to keep information about the new naval force. To do this, fill in the fields of the corresponding instance of the proxy class and pass it to the save method of the corresponding manager:

 //    - ManufacturerProxy manufacter = new ManufacturerProxy(); manufacter.Country = "Great Britan"; manufacter.Charge = new ContactInfo(Name: "D. Cameron", Phone: 1112233); manufacter.Ports = new List<ContactInfo> { new ContactInfo("Portsmun",2223344) , new ContactInfo("Dartford",3334455) }; // try { Navies.ManufacturerManager.Save(manufacter); } catch (Exception ex) { MessageBox.Show(ex.Message); } 

Then, if the data is correct, the following entry appears in the global:
^ n ("Great Britan") = $ lb ($ lb ("D. Cameron", 1112233), $ lb ($ lb ("Portsmun", 2223344), $ lb ("Dartford", 3334455)))

In case of incorrect data:



To access data in the nodes, an instance of the corresponding key-class is used:

 //   -      ManufacturerProxyKey key = new ManufacturerProxyKey("Great Britan"); ManufacturerProxy readed = Navies.ManufacturerManager.Get(key); // Navies.ManufacturerManager.Kill(key); 

Suppose we want to get all the ships on one condition - they must be of the 4th rank. To do this, fill in the remaining fields of the key class instance with empty values:

 //       List<ShipInfoProxy> allFourRankShips; ShipInfoProxyKey keyMask = new ShipInfoProxyKey(); keyMask.Country = ""; keyMask.ShipClass = new Classification{ ClassType = "", Rank = 4 }; keyMask.Name = ""; allFourRankShips = Navies.ShipInfoManager.GetByKeyMask(keyMask); 

Testing

Test bench: acer aspire 5553g-n936g50mn.
Scenario: deleting a global, creating a global, writing in an object way (without validation), clearing the global, writing in the standard way.
Notes: single-threaded application, tester loaded 25% of the processor, writing to the hard disk.

Given the few under-optimizations for saving 2,000,000 records like this:

^ wowsTest (kruis, 0, [3, 0], 1) = $ lb ($ lb ($ lb (1, 111111), $ lb (2, 111111)), $ lb (3, 2, 1), $ lb (1, 2, 3), 1000, $ c (6,6,6))
[...] - in object view, this is structure

Results:
Object 00: 01m: 00s.1959, Native: 00: 00m: 29s.7478 obj / native = 2.023
Caché GlobalsProxy Framework for recording without validation took 2 times longer than GlobalsAPI. With validation - in 3.

Conclusion

At this stage, the Caché GlobalsProxy Framework is a working prototype, the use of which speeds up the software development process, which implies the use of direct access to the globals of the GlobalsDB and Caché databases.

Caché GlobalsProxy Framework completely encapsulates the logic of working with the global GlobalsAPI tools, as well as the logic of working with metadata, in particular, automating validation.

Eventually:

1. Ensures logical data integrity. Now it is impossible to record anything and anywhere, since at first validation will be automatically done to the data, and only with its success will they be saved.
2. The software development process using GlobalAPI is accelerated many times.

Buns:

1. Creating your own types (structures) including indexes.
2. Partial key data retrieval.

Of the minuses should be noted slowdown, but in some projects it is quite possible to sacrifice part of it in favor of development speed.

Development

At the moment, within the context of a global context, its data scheme is uniquely defined. This is accomplished by creating multiple contexts with different data schemes for the same global, which is a bit inconvenient. In the future, the various global data schemes will be combined in one context.

It is also planned to organize a combination of indices. In addition to storing data, for example, for all 3 indices, it is possible to additionally use a combination of 2 out of 3 of these indices and store different structures for them, again within the same context.

Project in open access on github (GlobalsDB distribution kit is attached)

Guilty:

Gaydarzhi V.I. - for participating in the search for the project's theme and, most importantly, for believing in its favor.
Vityuk V.R. - for complicity in the specification and the creation of a metadata editor.
Kruchok S.I. - for the review.
Ancestors - for food and a roof over your head.
Nikolashin N.R. - for the review and most importantly - for the lack of faith in the project.