Hello SPF

Project Page

Download

Manual

The following tutorial shows how to create, persist and retrieve a simple entity using SPF. The full listing can be found here.

Creating the entity

Import the Sisyphus namespace:

using Sisyphus;

Subclass SpfEntity:

public class MyEntity : SpfEntity {

Model object values as primitive public fields:

  public bool BoolField; 
  public int IntField; 
  public double DoubleField; 
  public string StringField; 
  public DateTime DateTimeField; 

Provide a parameterless constructor:

  public MyEntity() {
  }

Persisting the entity

The entity is now ready to be persisted so now we need to create a test class. First we import the Sisyphus namespaces we will be using:

using Sisyphus;
using Sisyphus.Department;
using Sisyphus.Impl;

For now we will gloss over the purposes of the namespaces and move on to the test code itself. We will create a new class and a Main method:

public class MyEntityTest {

  public static void Main() {
  }
}

Next we will instantiate a ISpfDataStore implementation, in this case one for talking to SQL Server:

    ISpfDataStore store = new SqlDataStore("localhost", "sisyphus", "sa", "");

This example assumes you have a database called "sisyphus" already created on the local machine. These arguments to the constructor may have to be changed for your environment.

We could go into SQL Server and create a table for the entity. However, for this example we will let SPF do the work for us by using a data store builder:

    ISpfDataStoreBuilder storeBuilder = new SqlDataStoreBuilder(store);
    storeBuilder.CreateTable(typeof(MyEntity), true);

The above lines of code create a data store builder for SQL Server and then use it to create a table in which to store instances of our entity. The boolean value indicates whether or not to drop any existing tables first.

We now have a table in which to store our entities, if you go into SQL Server you will find a table called 'MyEntity' has been created with the following design:

You will see that SPF has created a column for each field and has created a primary key column called 'Id'. In SPF all entities have an GUID ID field which is inherited from SpfEntity.

The next step is to create an instance of our entity and populate it with some values:

    MyEntity myEntity = new MyEntity();
			
    myEntity.BoolField = true;
    myEntity.IntField = 666;
    myEntity.DoubleField = 3.1415926;
    myEntity.StringField = "Hello SPF";
    myEntity.DateTimeField = DateTime.Now;

There is nothing special about this stage and you may well want to add constructors to make this process somewhat less verbose.

In SPF, client data store interaction is done through a ISpfDataStoreBroker implementation. There are two provided depending whether or not you want to use COM+ or not. These are found in the Sisyphus.Enterprise and Sisyphus.Department namespaces respectively. In our example we will use the departmental broker:

   ISpfDataStoreBroker broker = new SpfDataStoreBroker(store);

We can now use the broker to persist the entity in the store specified:

   broker.Persist(myEntity); 

If we look in SQL Server we should see the result:

We can also use the broker we created to retrieve entities from the store. The following line retrieves a copy of the original entity:

    MyEntity myRetrievedEntity 
        = (MyEntity)broker.Retrieve(typeof(MyEntity), myEntity.Id);

As you can seem, the broker needs to be told the type and ID of the entity you want to retrieve. If the entity cannot be found then null is returned. The method returns value needs to be cast as the method returns the base of all entities, SpfEntity.

To test whether we managed to retrieve any values we shall add a simple test:

    Console.WriteLine("myRetrievedEntity.StringField = '{0}'", 
                      myRetrievedEntity.StringField);

With a bit of luck and the wind in a favourable direction, the following output should appear:

myRetrievedEntity.StringField = 'Hello SPF'   

That concludes this tutorial, in which we took advantage of the default behaviour of SPF. The default behaviour can be overrided to specify table and column names, field data types, entity constraints and business logic.