Beesnest Adapters

Unlike script engines, that can be used to develop many applications, adapters will be mostly unique for a specific application. In fact they will be part of the application. Adapter is a dynamically loaded library that adds some functionality to Beesnest. The name Adapter used to refer to an object that adapt between Beesnest and some other software or hardware device. But Adapters are not limited for just that any more.

See here how to build an adapter.

Creating an instance

An adapter is a general concept, in order to use one you need to get an instance of this adapter (for programmers: classes and objects).
You can configure an adapter to create just one instance at a time, one instance per user at a time or unlimited instances. If an adapter is set not to create unlimited instances, it can also be stored for the user over multiple pages (if an adapter is set to create unlimited instances, there is no manning of storing it, every request for this adapter creates a new one). More on how to get an instance of an adapter, later.

Configuring an adapter

Every adapter has to have a short configuration bnc file. In this file you will define the name of this adapter, how to create instances, if it can be stored or not and if so, for how long. In addition any specific configuration of the adapter will be in this file. The configuration of an adapter is very similar to the configuration of a script engine.
A sample configuration file will look like this:
<Adapter> <TestAdapter> <File-Name>Adapters/TestAdapter/TestAdapter.dll</File-Name> # Can different users get an instance at the same time? <Multi-User>yes</Multi-User> # Can different threads of the same user get an instance at the same time? <Multi-Engine>no</Multi-Engine> # Can this adapter be stored? # Relevant just if it is not Multi-Engine. <Storable>yes</Storable> # How long this adapter can stay taken by a user and idle # Relevant just if adapter is Storable. <Sec-To-Logout>600</Sec-To-Logout> # Specific configuration goes here .... </TestAdapter> </Adapter>
Adapters is the common entry for all the adapters.
TestAdapter Here you have to change the entry name itself. This will be the name you choose to call this adapter, and the name you will use in your script to get this adapter. Every adapter has to have a different name.
File-Name Is the library file (DLL, sa) where the adapter is. It can be relative (to Beesnest executable) or absolute path.
Multi-User Can this adapter give more than one instance at the same time (yes/no)?
Multi-Engine Can this adapter give more than on instance to one user (yes/no)?
Storable Can this adapter be stored between pages (yes/no)?
Sec-To-Logout How long (in seconds) can this adapter be stored when idle?

Beesnest tracks the user adapters by the adapter name. You can have more than one entry in the configuration, for adapters that will be loaded from the same library, as long as the adapters have different names. You can even configure these adapter differently, Beesnest will see them as two different adapters. Similar situation exist with engines, you can read more about it.

Using an adapter

The commands for using an adapter depend on the scripting language you use. However in every language you should have the same four operations.

• Create (bn_adapter in BnPython) Will return an instance of an adapter name. It either takes it from the storage or creates a new one. Actually it returns just an adapter ID, but you should refer to it as the adapter itself. If the adapter cannot be created (doesn't exist or taken by other user) it will return zero.


• Release (bn_free in BnPython) Will release an adapter. If you do not call Release on an adapter it will be either get released in the end of the script or get stored for the next page, depend on the adapter configuration. In any case all the adapters get released when the user logs out. An adapter will also releases itself if the idle time is over.


• Read (bn_read in BnPython) Read some specific data from the adapter. the "name" of the data to read is given as an argument.


• Write (bn_write in BnPython) Write some specific data to the adapter. the "name" of the data to write as well as the data itself is given as arguments.

Two examples for general purpose adapters

I have two examples for adapters that can be used as a generic "tools". One is an embedded SQLite database, the other is a Windows Serial Port (RS232) adapter.

The BnSQLite adapter is a simple wrapper for the SQLite database. it is only use the execute command to execute SQL code. If you set the database file as "read only" the database will be read only. If the database file does not exist, SQLite will create a new database (and database file). after executing a SELECT command, you can read the results record by record. BnSQLite connects to the database when you create it, and disconnect when you release it. It can be stored, with all the data that is in the current record-set.

The BnSerialPort adapter can send and receive data from the computer serial port (COM). This adapter will compile just under Windows. This is an example for adapter the can create just one instance at a time. If one user uses it, no other user can get it. You can store it and keep the connection to the serial port open.

For more details about this adapters and how to use them, you should look at the comments in the adapters source code ( BnSQLite and BnSerialPort).