BSOleDB Class. Database access

Ole DB providers allow the access to data stores which range from simple text files or spreadsheets to complex databases like Oracle, Microsoft SQL Server or Sybase ASE. BSOleDB class simplifies the access to data stores through Ole DB, allowing it to carry out queries and execute commands using the SQL language.

BSOleDB(string strcon)

Class constructor

string strcon: OLE connection string with the database. The content and formatt of this connection string depends on the type and manufacturer of the data store. On the appendix A of this manual the typical connection strings for the most popular and common data stores are detailed. Contact your database administrator in case of doubt, he must supply you with the correct connection string.

bool Open()

Open the connection with the database.

Output: It will return true if the operation has been successful, otherwise it will return false and generate a level 0 error message in the console.

bool Close()

Close the connection with the database.

Output: It will return true if the operation has been successful, otherwise it will return false and generate a level 0 error message in the console.

ArrayList Query(string sql)

Performs a SQL query against the database and returns the result as an ArrayList where each position corresponds with one row of the query result. In order for this method to work correctly the database connection must be opened calling the method "Open".

Output: An ArrayList containing the result of the query. In the case of an error at any point through out this proccess it will return null and generate a level 0 error message in the console.

bool Exec (string sql)

Executes a SQL command with no result (CREATE, UPDATE, DROP...) against the database,

Output: It will return true if the operation has been successful, otherwise it will return false and generate a level 0 error message in the console.

BSNode class. Main constructive element

Any application based on BeamSever defines internally a graph where all the server elements are interconnected: users, rooms, logics... The BSNode class is the parent from which all the nodes contained in the graph are extended. All the nodes in the graph contain a list of linked nodes.

The power of BeamServer lies in the fact that these nodes can subscribe between one and other, so any change performed in a node is known by the subscribers and they can act in consequence. Each node can be local or remote, in case of remote nodes all the neccesary updates are done through the network in a transparent and automatic way.

A virtually unlimited number of attributes and variables can be defined in each BeamServer node. When the value of an attribute changes the new value is transmitted to nodes subscribed to the owner node. Otherwise, changes in variables don't generate any update events. Unlike attributes, variables can't be accessed from the client side.

About subscriptions

Each node can subscribe to any node, whether or not it is contained in its node list. Once the subscription is done, the first node will be notified of any changes in the second node, however they are local or remote.

Changes in subscribed nodes are notified through the call of virtual methods, which we can override in order to handle events. Notified changes are as follows:

  1. - Each node adds or removes nodes in its node list.
  2. - A node attribute value is changed.
  3. - A node attribute value of any node contained in the node list of a node is changed. This event is not recursive, changes from second depth level on up are not notified.
  4. - The node is being destroyed.
  5. - A node contained in the node list of a node is being destroyed.

Virtual methods related with attribute changes are unique, whether the attributes are created, modified or destroyed. We can know when an attribute is being destroyed because the new value will be null.

Communication between nodes

Nodes can send data between themselves through the combined use of the "SendObject" method and the "OnObjectReceived" virtual method, which syntax is detailed later in this document. A big part of the weight of the development of an application based on BeamServer is about the definition of the "OnObjectReceived" method in the differents nodes.

When the communication is between remote nodes, data is serialized at the origin and deserialized at the destination in a transparent way.

Virtually any data type can be transferred between nodes, however when the communication is done between remote nodes we should take into account some platform compatibility issues. The following data types can be used safely, individually or combined.

  1. - Hashtable
  2. - ArrayList
  3. - double
  4. - int
  5. - uint
  6. - bool
  7. - DateTime
  8. - nul

Each of these data types corresponds with another on each BeamServer supported platform. Go to the client documentation to search for more information about each platform.

int GetId()

Output: Unique ID automatically generated by BeamServer.

string GetName()

Output: Node name, set in the creation. It is useful for node identification and search operations inside the server.

BSNode(string name, Hashtable param)

Class constructor.

string name : Node name.

Hashtable param : Initial node attributes.

bool isRemote()

Output: It will return true if it is a remote node, otherwise it will return false.

void AddChildNode(BSNode node)

Adds a node to the node list.

BSNode node : The added node.

void RemoveChildNode(int nodeId)

Removes a node from the node list.

int nodeId : Unique ID of the node we want to remove.

void SetChildAttribute(int nodeId, string name, object value)

Updates the attribute value inside a node contained in the node list.

int nodeId : Unique node ID.

string name : Attribute name.

object value : New attribute value.

void SetChildVariable(int nodeId, string name, object value)

Updates the variable value inside a node contained in the node list.

int nodeId : Unique node ID.

string name : Variable name.

object value : New variable value.

BSNode FindChildNode(string name)

Searchs for a node in the node list and returns it.

string name : Node name.

Output: It will return the node if found, otherwise it will return null.

void SetAttribute(string name, object value)

Updates an attribute value.

string name : Attribute name.

object value : New attribute value.

void SetVariable(string name, object value)

Updates a variable value.

string name : Variable name.

object value : New variable value.

object GetAttribute(string name)

Gets an attribute value.

string name : Attribute name.

Output: Attribute value.

object GetVariable(string name)

Gets a variable value.

string name : Variable name.

Output: Variable value.

void IncAttribute(string name, int inc)

Increments an attribute value (only for numeric attributes).

string name : Attribute name.

int inc : Incremented quantity(positive or negative).

void IncVariable(string name, int inc)

Increments a variable value (only for numeric variables).

string name : Variable name.

int inc : Incremented quantity(positive or negative).

void SubscribeToNode(BSNode node)

Subscribes the current node to other node.

BSNode node : The node you want to subscribe to.

void UnsubscribeFromNode(BSNode node)

Unsubscribes the current node from other node.

BSNode node : The node you want to unsubscribe from.

void SendObject(int nodeId, object data)

Sends data to the specified node. See the "Communication between nodes" section in order to see the supported data types.

int nodeId : Receiver node.

object data : Sent data.

void Destroy()

Sends a notification to all nodes subscribed to this node and destroys all references contained in the BeamServer internal objects, in order that it can be removed by the garbage collector.

Closes the connections opened by this node and calls the Destroy method in all the nodes of its node list.

void CloseConnection()

In case of remote node, the network associated connection is closed.

(virtual) BSNode CreateNode(int owner, string name, Hashtable param)

By default this node creates and returns a BSNode class object. However, when classes extended from BSNode are created other returned object classes can be useful. Overriding this virtual method the developer has the freedom to create his own server structure in an automatic way.

int owner : Not useful.

string name : Created node name.

Hashtable param : Default node attributes.

(virtual) void OnChildAdded (int nodeId, BSNode node)

Virtual method, override it for server logic. This method is called when a node is added to the node list of a node we are subscribed to.

int nodeId : Unique ID of the node we are subscribed to.

BSNode node : Added node.

(virtual) void OnChildRemoved (int nodeId, int childId)

Virtual method, override it for server logic. This method is called when a node is removed from the node list of a node we are subscribed to.

int nodeId : Unique ID of the node we are subscribed to.

int childId : Unique ID of the removed node.

(virtual) void OnChildAttributeUpdated (int nodeId, int childId, string name, object value)

Virtual method, override it for server logic. This method is called when the value of an attribute of a node contained on the node list of a node we are subscribed to is modified.

int nodeId : Unique ID of the node we are subscribed to.

int childId : Unique ID of the node whose attribute is being modified.

string name : Attribute name.

object value : Attribute new value.

(virtual) void OnAttributeUpdated (int nodeId, string name, object value)

Virtual method, override it for server logic. This method is called when the value of an attribute of a node we are subscribed to is modified.

int nodeId : Unique ID of the node we are subscribed to.

string name : Attribute name.

object value : New attribute value.

(virtual) void OnObjectReceived (int nodeId, object data)

Virtual method, override it for server logic. This method is called when the node recieves data.

int nodeId : Unique ID of the sender node.

object data : Received data.

(virtual) void OnChildBeenDestroyed(int nodeId)

Virtual method, override it for server logic. This method is called when the "Destroy" method of a node contained in its node list is called.

int nodeId : Unique ID of the destroyed node.

(virtual) void OnLogin(string suc)

Virtual method, override it for server logic. Remote nodes which sporadically connect to our application must pass through a verification process inside the BSServer class before they can exist in our server structure. Once the verification has been successful, the node is created and this method is invoked.

string suc : 'T' if the verification is successful.

(virtual) void OnJoinNode(int nodeId)

Virtual method, override it for server logic. This method is called when this node joins to another node, after this point the first node will be contained in the node list of the second node.

int nodeId : Unique ID of the joined node.

(virtual) void OnDestroy()

Virtual method, override it for server logic. This method is called when the node is being destroyed.

ArrayList GetAttributes()

Output: Returns an ArrayList with all the node attributes.

ArrayList GetVariables()

Output: Returns an ArrayList with all the node variables.

BSNode GetChildNode(int nodeId)

Output: Returns the node with the specified ID from the node list. If not exists returns null.

Hashtable GetChildNodes()

Output: Node list.

String GetXMLString()

Output: Node information in XML formatt.

void SetName(String newname)

Changes the name of the node.

BSServer class. The entry point

Safe server close

When the application performs operations wich require that the server is stopped, the following intuitive code is not enough:

void UnsafeOperations()
{
server.Stop()
...

//opperations
...
server.Start()
}

The "Stop" method invocation is asynchronous but there is only a short period of time between the invocation and the real close of the server. It is possible that when we invoke the "Start" method again the server will not be closed yet.

In order to avoid this problem, we can use an event oriented architecture, through the use of C# delegates:

A delegate is defined inside the BSServer class:

public delegate void serverStopHandler();

and two methods:

public void addServerStopListener(serverStopHandler handler)
public void removeServerStopListener(serverStopHandler handler)

the correct way to perform safe operations is:

void SafeOperations()
{
server.addServerStopListener(new BSServer.serverStopHandler(OnServerStop));
server.Stop();
}

private void OnServerStop()
{
server.removeServerStopListener(new BSServer.serverStopHandler(OnServerStop));
...

//opperations
...
server.Start();
}

An important use of these methods could be to ensure the server is closed before closing the application.

This class defines another three methods:

BSServer()

Class constructor.

void Start(string serverIp, int serverPort)

Starts the server and creates the basic structures, the server will keep listening from now on.

string serverIp : IP address of our server.

int serverPort : Listening port for new connections.

(virtual) BSNode CreateUser(string name, Hashtable param)

By default it returns a BSNode class object with the name and attributes specified. This method can be overridden in order to customize the creation of nodes associated with the users who connect to the server.

string name : Node name of the connected user.

Hashtable param : Default attributes..

Output: BSNode class object or BSNode class extended object associated with a user.

(virtual) bool VerifyUser(string user, string pass)

The server security relies on this virtual method. By default it always returns true but the developer can customize it with a user name/password verification routine.

string user : User name.

string pass : Password.

Output: It will return true if verification is successful, otherwise it will return false.

BSTrace class, application window messages

The developer can invoke this static class in order to show text information inside the application's main window.

A verbose level can be defined for the class and for each message, only messages with a verbose level less or equal than the verbose level of the class are showed.

void SetVerboseLevel(int level)

Selects the current verbose level.

int level : Verbose level. Greater than 0 or equal.

void Out(object message, int level)

Shows a message if the specified level is equal or lower than the current verbose level.

object message : Showed message.

int level : Message verbose level.

void Line(int level)

Shows a line if the specified level is equal or lower than the current verbose level.

int level : Verbose level.