Introduction to the BHoM_Adapter
Before reading this page, have a look at the following pages:
and make sure you have a general understanding of:
In this page you will find a first overview about what is the BHoM Adapter.
- What is an adapter?
- The Adapter Interface
- Your Toolkits' Adapter extends the base BHoM_Adapter
- Adapter Actions
- Next steps
As shown in the Structure of the BHoM framework, an adapter is the piece of code responsible to actuate the connection (import/export) between different software packages.
The Base BHoM_Adapter includes a series of methods that are common to all software connections. Specific Adapter implementations are included in what we call the Toolkits.
We will see how to create a Toolkit later; however consider that, in general, a Toolkit is simply a Visual Studio solution that can contain one or more of the following:
- A BHoM_Adapter project, that allows to implement the connection with an external software.
- A BHoM_Engine project, that should contain the Engine methods specific to your Toolkit.
- A BHoM_oM project, that should contain any oM class (types) specific to your Toolkit.
The BHoM_Adapter is one of the base repositories, with one main Project called BHoM_Adapter.
This project takes care of the backing actions needed to link a software to another software. It's the core communication interface that the BHoM exposes to allow for information interchange between different software packages.
It's important to keep in mind that the BHoM_Adapter should be seen as the background helper to connect between different software.
This is because when you actually want to implement a new software connection, or work on an existing one, you will have to create and work not on the BHoM_Adapter, but on a specific Toolkit.
This important aspect needs to be understood here:
when you want to create the connection between the BHoM and another software, you will have to create what is called a Toolkit. A Toolkit is yet another repository that contains a Visual Studio solution. A Toolkit is backed by (meaning that it contains, or better, extends) the BHoM_Adapter.
A Toolkit can be seen as the a concrete implementation of the BHoM_Adapter, meaning that it's the piece of code that actually implements the connection between different software.
You can read more on the Toolkit here.
First and foremost feature of the BHoM_Adapter are the its Adapter Actions.
The Actions correspond to the front-end methods available to the end-user to connect BHoM with any external software.
For example, in Grasshopper, there will be a component representing each action, so as in Dynamo; in the same way, in Excel you will find formulas corresponding to these methods. To see them in their UI context, taking the example of Grasshopper, you can find these methods in the Adapter subcategory:
So what are the Adapter actions?
They are actually an advanced concept, of which for now you just need to know the existence and some general things. Let's have a first overview of them all:
- Push: if objects don't exist yet, they are created, if they do, they will be replaced. It will also handle the case where the number of objects changes between pushes.
- Pull: This simply grabs all the objects that satisfy a certain query. If no query is specified, all the objects of the connected model will be taken. You can read more about the queries in a later paragraph.
- UpdateProperty: Instead of replacing/modifying entire objects, this will update one of their property with a new value.
- Delete: This will delete all the objects that match a specific filter.
- Execute: This is used to ask the external software to execute a specific command such as Run analysis, for example.
An important thing to notice and understand – as you might have guessed from their description – is that these methods take care of basic, fundamental things, like ID assignment, avoiding object duplication, distinguishing which object needs updating versus replacing, etc.
The following is an excerpt of the BHoMAdapter.cs file contained in the "BHoM_Adapter" project.
The Public Adapter Methods have been designed to be as useful and flexible as they can possibly be. Their definition has been abstracted as much as possible, so they can be validly applied across any kind of implementation, with a minimum required effort. If you need to, you can also override them.
This means that when you want to contribute to the BHoM and create a new software connection, you will not need to implement the Public Adapter Methods, at least in most of the cases.
So what is it that you need to implement?
The answer is: the so called CRUD Methods. We will see them in the next page.
Additional note: overriding the Public Adapter Methods
If you need to re-implement one or more of the adapter methods for some specific reason, you are always able to do so.
That is because all those methods are defined asvirtual, so you canoverridethem.This might be required only in very particular cases.
You might have noticed that the Adapter Actions take particular input parameters that need to be explained: the Requests, the ActionConfig, and the Tags.
Their understanding is not essential to grasp the overall mechanics; however you can find their explanation in the Adapter Actions - Advanced parameters section of the wiki.
Proceed to get a better understanding of the Adapter Actions and their backing CRUD methods.