The Business Rules Engine

Step 1: Create the Application

The first thing you will need to do when writing a CodaServer application is to gain access to a server. This could either be a preexisting server instance, or a new one set up using the handy instructions. The tool used to connect to the server and do work is called CodaClient, and you can find instructions on setting it up here.

Assuming everything is set up correctly, you can go to your CodaClient directory and type the following:

./runClient.sh 

You should now see something like this:

CodaClient 1.0 Alpha
Connected!

Coda %: 

Now we're cooking with gas!

Before we proceed, we need to talk a little about how CodaServer works. CodaServer is essentially a middleman that takes input from application languages such as PHP, Java, or C#, processes it for business rules, and writes the necessary changes to a relational database system such as MySQL, Oracle, or Microsoft SQL Server. In order to connect to these relational databases, it needs to store the connection information. These connection details are called "Datasources" within the CodaServer environment.

Each CodaServer application has between one and three datasources associated with it, one each for Development, Testing, and Production. The former is the only one that needs to be defined when the application is first created, since the other two won't come into play until the application reaches a higher level of maturity.

A datasource requires of the following details: The name of the CodaServer driver to use for the connection (usually determined by the database vendor), the hostname of the server, the username, the password, and the schema name.

For Tina's database, you decide to use the MySQL driver because that is the most reliable one at this time. At the prompt type:

CREATE DATASOURCE students_dev DISPLAYED AS 'Students Development Database' (
     hostname = 'localhost', 
     username = 'students', 
     password='chang3m3', 
     schema='students_dev', 
     driver = 'org.codalang.codaserver.mysqldriver.MySQLDriver'
)
USING ADMIN 'root':'root_password';

with the 'root' and 'root_password' replaced by a username on your database server that has permission to create schemas. Press enter to send the command to the server. You can type it over multiple lines if you would like; it is the semicolon (;) at the end of the statement that sends the current command buffer to the server. The DISPLAYED AS clause is optional, and provides a human-readable description of the datasource.

Note: MySQL sometimes has problems with its connection host strings. While CodaServer creates a user that can connect from any host (%) sometimes a MySQL server will still not let the created user connect from localhost. if you receive errors indicating that you can't connect to a datasource, this is a good place to look.

You should get a message saying the statement was successful. You can verify by typing in the following command:

SHOW DATASOURCES;

Now you are ready to create the application itself. Type in the following command and hit enter:

CREATE APPLICATION students DISPLAYED AS 'Student Contact Information' 
ON DATASOURCE students_dev PREFIX c_; 

The 'students_dev' datasource created before will become the DEV datasource for the application, and all changes you make to the schema will happen there first. The prefix provided is what CodaServer will use to namespace its metadata tables within the database. To avoid collisions, it is best to choose something here that you know you won't use for your own table names. It is also optional, although highly recomended.

Finally, you need to set your new application as the active application for your session. To do this, type:

SET APPLICATION students.dev;

and hit enter. It is recommended that you do this every time you connect to CodaServer, since many operations (such as all data manipulation statements) can only be performed if you set the application and environment you are working in. The SET APPLICATION command only applies to your current connection had has no long-term ramifications in the system.

That was pretty painless, huh? Now you have now accomplished the following:

  • Created a new schema on MySQL for the students database.
  • Told CodaServer how to connect to it via a datasource.
  • Created the application and told it to use that datasource for its development work.
  • Set your current CodaServer session to use this application for all subsequent commands.

Next you get to build the new application!