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:
# Can different users get an instance at the same time?
# Can different threads of the same user get an instance at the same time?
# Can this adapter be stored?
# Relevant just if it is not Multi-Engine.
# How long this adapter can stay taken by a user and idle
# Relevant just if adapter is Storable.
# Specific configuration goes here ....
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
Is the library file (DLL, sa) where the adapter is. It can be
relative (to Beesnest executable) or absolute path.
Can this adapter give more than one instance at the same time
Can this adapter give more than on instance to one
Can this adapter be stored between pages (yes/no)?
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
, 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
- 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
Two examples for general purpose adapters
I have two examples for adapters that can be used as a generic "tools". One is an
other is a Windows Serial Port (RS232) adapter.
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.
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
For more details about this adapters and how to use them, you should look at the
comments in the adapters source code