The CRUD methods

The CRUD methods are the actual methods have to be implemented in the specific Toolkits. Their scope has to be kept strictly to a minimum, as explained below.

Create

Create must take care only of Creating, or exporting, the objects. Anything else is out of its scope.

For example, a logic that takes care of checking whether some object already exists in the External model – and, based on that, decides whether to export or not – cannot sit in the Create method, but has rather to be included in the Push. This very case (checking existing object) is already covered by the Push logic.

The main point is: keep the Create simple. It will be called when appropriate by the Push.

The Create in practice

The Create method scope should in general be limited to this:

• calling some conversion from BHoM to the object model of the specific software and a
• Use the external software API to export the objects.

If no API calls are necessary to convert the objects, the best practice is to do this conversion in a ToSoftwareName file that extends the public static class Convert. See the GSA_Toolkit for an example of this.

If API calls are required for the conversion, it's best to include the conversion process directly in the Create method. See Robot_Toolkit for an example of this.

In the Toolkit template, you will find some methods to get you started for creating BH.oM.Structure.Element.Bar objects.

AssignNextFreeId

This is a method for returning a free index that can be used in the creation process.

Important method to implement to get pushing of dependant properties working correctly. Some more info given in the Toolkit template.

Read

The read method is responsible for reading the external model and returning all objects that respect some rule (or, simply, all of them).

There are many available overloads for the Read. You should assume that any of them can be called "when appropriate" by the Push and Pull adapter actions.

In practice

The Read method scope should in general be specular to the Create:

• Use the external software API to import the objects.
• Call some conversion from the object model of the specific software to the BHoM object model.

Like for the Create, if no API calls are necessary to convert the objects, the best practice is to do this conversion in a FromSoftwareName file that extends the public static class Convert. See the GSA_Toolkit for an example of this.

Otherwise, if API calls are required for the conversion, it's best to include the conversion process directly in the Read method. See Robot_Toolkit for an example of this.

Update

The Update has to take care of copying properties from from a new version of an object (typically, the one currently being Pushed) to an old version of an object (typically, the one that has been Read from the external model).

The update will be called when appropriate by the Push.

In practice

WIP

Delete

The Update has to take care of deleting an object from an external model. The Delete is called by these Adapter Actions: the Remove and the Push. See the Adapter Actions page for more info.

In practice

Deletion of objects with tag

By default, an object with multiple tags on it will not be deleted; it only will get that tag removed from itself.

This guaranties that elements created by other people/teams will not be damaged by your delete.