Adapters are software connecting to the Orchestra server and calling Adapt_Outlet on an outlet.
The adapters are the things that actually make Orchestra useful. Adapters give behavior to entities.
Without adapters, Orchestra does absolutely nothing. Orchestra's job is to have a list of entities, and whenever someone interacts with an entity through Invoke or Publish, Orchestra routes that request to the right adapter for it to handle it. The Inquire call also exists, but seems to be legacy and can just be ignored.
Almost every other possible call to Orchestra is just system administration to set up entities and their routings to the correct adapters.
An adapter is a program handling Invoke calls.
A subscriber is a program handling Publish calls. Subscribers work a little bit differently and will not be discussed on this page.
NOTE: Adapter is often used instead of the word Outlet, because 99% of the time an adapter creates the outlet it will adapt on, and no other adapter will ever adapt that outlet, making the outlet and adapter almost two indistinguishable concepts.
¶ Invoke
Invoking an entity is asking that entity to do something. The underlying adapter will actually do the job.
One can think of invoking an entity as something similar to calling a method of a class in OOP programming.
TODO: It is possible to invoke from the AVU, explain it in the avu page
¶ Method
In Orchestra, which method of an entity to invoke is defined by the Method argument of Invoke_Entity, and is an enum defined in the taxonomy.
¶ Precedence
A previous version of Orchestra tried to provide a mechanism similar to inheritance and method overloading through the Precedence argument. This allowed one to have multiple adapters handle the same method, and whichever adapter was connected through the highest precedence would handle the invoke, with the ability to delegate to the next highest precedence at will.
This is no longer the case. The Precedence argument is only present as a legacy of this system. It still is in use, but only matches adapters connected by the exact same Precedence an invoke call is issued with.
This means if I have adapter A connected to an entity with Precedence 0, and adapter B connected to the same entity with Precedence 1, any invoke call issued with Precedence 0 will be handled by adapter A, and any invoke call issued with Precedence 1 will be handled by adapter B. Any invoke with Precedence 2 or more will fail.
¶ Connecting an entity to an adapter
The connection of an entity to an adapter is done by a middle-man: an Outlet
¶ Outlets
An outlet is a special entity that has been granted access to greater computational resources (mostly allocating queues), to perform more complex peer-to-peer networking tasks/requests. Calling ACTIVATE on an entity turns that entity into an outlet.
On one side of an outlet, we Connect an entity to the outlet. We may decide to only Connect a specific method, and/or a specific precedence, or we may decide to connect all methods and all precedence.
On the other side of the outlet, we Adapt the outlet from an adapter.
An entity may be connected to multiple outlets, and multiple entities may be connected to the same outlet.
A good mental model of what is happening is that an adapter is a client talking to an Orchestra server. Then the adapter calls Adapt on an outlet, and registers itself as the server that will handle requests. The adapter is just waiting for an incoming request to process.
Another good mental model is to think of outlets as the equivalent of Interfaces in OOP. We don't know yet what will implement that interface, just like we don't know yet what adapter will adapt on that outlet, but if we decide to connect on that outlet, it means we have some expectation of what methods will be implemented to do what.
Outlets are entities, and therefore can themselves be connected to an outlet and be invoked. A common pattern is to connect an outlet to itself. Just like in OOP, most of the time we call a method on an instance of the class, sometimes we want to call a static method of the class. A prime example of this is if our class has a constructor. This is the reason why the recommended way of creating an Object entity is to Invoke with Method=AvMethod.CREATE on the Object adapter outlet itself, which always has the EUID <11> (see [Orchestra Standard Adapters](./Orchestra Standard adapters)).
Having the outlet connected to itself is a common pattern used to provide the equivalent of static method of a class in OOP. It is used to Invoke any method we don't want to Invoke on any specific entity connected to that adapter.
¶ Special invoke arguments
The arguments entity, outlet and authorization the adapter receives can be used to determine what entity was invoked, and what outlet the rendez-vous happened in and what authorization code was used.
Note that the EUID received by the adapters are the real EUID of the entity/outlet, after potential redirections (see the redirect_entity avial call).
¶ Create an adapter with AvesTerra
WARNING: This is how you create an adapter at the AvesTerra layer, not using our LEDR-made Orchestra layer. Though it is very good to understand how this works, any production system should make use of the Orchestra layer.
Create an 'adapter' program in your language of choice. Here we'll use Python because it's easy to read.
TODO: Explain what value to use for AUTH
Create the entity that will be invoked
myentity = av.create_entity(
name = 'My entity',
authorization = AUTH,
)
Then create the outlet that will connect the entity to the adapter.
Create an entity and activate the entity to turn it into an outlet
myoutlet = av.create_entity(
name = 'My outlet',
category = AvCategory.OUTLET, #good practice, not required
authorization = AUTH,
)
av.activate_entity(
outlet = myoutlet,
authorization = AUTH,
)
You can verify an entity has been activated (turned into an outlet) by looking at the Activated field of its metadata.
You'll need to print the EUID of the outlet (myoutlet) and use the show command to see its metadata in the avu
Connect the entity to the outlet with Method NULL and Precedence NULL
av.connect_method(
entity = myentity,
outlet = myoutlet,
authorization = AUTH,
)
From now on, any Invoke call done on myentity will be forwarded to myoutlet.
You can verify an entity has been connected to an outlet by looking at the Connections field of its metadata. You'll need to print the EUID of the entity (myentity) and use the show command to see its metadata in the avu
Call Adapt_Outlet on the outlet to listen to handle the next Invoke call the outlet will receive
def callback(**kwargs) -> AvValue:
print(f'Callback: {kwargs}')
return AvValue.encode_text('Hello from the adapter!')
av.adapt_outlet(
outlet = myoutlet,
authorization = AUTH,
callback = callback,
)
Now to invoke this entity, create another 'invoker' program.
For the sake of this guide, we're gonna hard-code the value of the entity to invoke by printing it in the 'adapter' program and copy/pasting it in the 'invoke' code like so
entity = av.AvEntity.from_str('<0|0|165120>')
Replace this EUID by the entity myentity the adapter created
Then invoke this entity with any argument you want
result = av.invoke_entity(
entity = entity,
method = AvMethod.COUNT,
attribute = AvAttribute.SCHOOL,
authorization = AUTH,
)
print(f'The result is {result}')
Et Voilà.
First launch 'adapter', then launch 'invoker' giving the right entity, and the 'adapter' should receive the Invoke, print the argument received, and return the return value.
The adapter should print something like
The entity is <0|0|165120>
The outlet is <0|0|165121>
adapting...
Callback: {'entity': Entity(0, 0, 165120), 'outlet': Entity(0, 0, 165121), 'method': <AvMethod.COUNT: 17>, 'attribute': <AvAttribute.SCHOOL: 124>, 'name': '', 'key': '', 'value': AvValue(0, "b''"), 'parameter': 0, 'resultant': 0, 'index': 0, 'instance': 0, 'offset': 0, 'count': 0, 'aspect': <AvAspect.NULL: 0>, 'context': <AvContext.NULL: 0>, 'category': <AvCategory.NULL: 0>, 'klass': <AvClass.NULL: 0>, 'event': <AvEvent.NULL: 0>, 'mode': <AvMode.NULL: 0>, 'state': <AvState.NULL: 0>, 'condition': <AvCondition.NULL: 0>, 'precedence': 0, 'time': AvTime(1970, 1, 1, 8, 0), 'timeout': 0, 'auxiliary': Entity(0, 0, 0), 'ancillary': Entity(0, 0, 0), 'authority': AvAuthorization('928d3e6b-af48-404d-ab7c-920b7f61658c'), 'authorization': AvAuthorization('928d3e6b-af48-404d-ab7c-920b7f61658c')}
The authorization tokens are from my local appliance I use as a playground, it's not a leak
The invoker should print something like
The result is AvValue(5, "b'Hello from the adapter!'")
¶ Create an adapter with Orchestra
TODO: detail this section. We probably want to move the adapter class to the orchestra python binding first.
Just create an instance of the Adapter class and you're basically set. You can then connect any entity to the outlet by getting it through the mount adapter
¶ TODOs
- explain better the invoke queue that happens in the outlet, and what is a rendez-vous
- mention the
adaptingandinvokingfiel of the medata - mention that if an adapter dies before receiving an invoke, its adapt call is still queued in the outlet and it will blow up when there is a rendez-vous