Back to contents pageHow to create a client application for a user-defined schema

How to create a client application for a user-defined schema

Summary

This article shows how to create a client application that interacts with the CarModule.CarData schema server implementation from How to implement the operations for a user-defined schema. In this example you will learn how to create applications that use your own data model definitions or connect to your own schema server implementations.

Prerequisites

You should know the information in the following articles:

Example material

Save this link to get a zip file of the example material

Guide

Adding the references to the assemblies

First, we need to add a reference to the CarModule.dll assembly and the CarModule-CarData.dll schema assembly (generated in How to create a user model using Data Dictionary). It is usual to also reference UbisensePlatform.dll, which contains definitions that you are likely to use. The UbisensePlatform.dll file can be found in the directory where the Ubisense software was installed, in the bin folder (C:\Program Files\Ubisense 2.1\bin by default).

Preparing the schema

A user-defined schema has the same usage as other schemas.

1) Instantiating and connecting

Create a Ubisense.CarModule.CarData.Schema object and call ConnectAsClient on it:

    // Creates a cached schema client
    Ubisense.CarModule.CarData.Schema carDataSchema =
        new Ubisense.CarModule.CarData.Schema(false);

    // Connects it to the CarData schema at the server
    carDataSchema.ConnectAsClient();

2) Adding event handlers

Create methods with the appropriate signature to be a valid event handler of the CarHasProperties relation:

    void OnInsert(Ubisense.CarModule.CarData.CarHasProperties.RowType insertedRow)

    void OnUpdate(Ubisense.CarModule.CarData.CarHasProperties.RowType oldRow,
        Ubisense.CarModule.CarData.CarHasProperties.RowType newRow)

    void OnDelete(Ubisense.CarModule.CarData.CarHasProperties.RowType deletedRow)

Now, subscribe those methods to the appropriate CarHasProperties event. Remember to add an establish handler to ensure your client is always up-to-date with the state of the schema relation:

    carDataSchema.AddEstablishHandler(GetCars);
    Ubisense.CarModule.CarData.CarHasProperties.AddInsertHandler(carDataSchema, OnInsert);
    Ubisense.CarModule.CarData.CarHasProperties.AddUpdateHandler(carDataSchema, OnUpdate);
    Ubisense.CarModule.CarData.CarHasProperties.AddDeleteHandler(carDataSchema, OnDelete);

3) Adding a monitor Form

If the schema server is not running, your application's schema will not be able to connect to it. Add a Ubisense.UBase.MonitorForm object to your application's Program class, in Program.cs to diagnose any future problems.

Ubisense.UBase.MonitorForm mf = new Ubisense.UBase.MonitorForm();

Using the schema

1) Iterating over the CarHasProperties relation

Get a ReadTransaction object from your CarData instance, and use the car_ index method to iterate over the elements that match the given parameter, or, don't use one to iterate over the whole contents of the CarHasProperties relation:

    using (Ubisense.CarModule.CarData.ReadTransaction xact =
        carDataSchema.ReadTransaction())
    {
        foreach (Ubisense.CarModule.CarData.CarHasProperties.RowType row
            in Ubisense.CarModule.CarData.CarHasProperties.car_(xact))
        {
            // row.car_;
            // row.car_properties_.car_model_;
            // row.car_properties_.vin_;
        }
    }

2) Calling the schema's Remote operations

The CarData schema defines 3 operations; you can call them like this:

    // Finds the row for the given Car parameter and returns the
    // properties found in that row
    carDataSchema.get_car_properties(car, out properties)

    // Creates a new entry with the given parameters
    // If an entry for that Car object already exists,
    // it changes its properties.
    carDataSchema.set_car_properties(car, properties);

    // removes the entry for the given Car object
    carDataSchema.remove_car_properties(car);

Note that you should normally use a caching client so that you can query the local cache rather than calling get_car_properties. This is so you have predictable scalability. Using get_car_properties and an event client is fine if you only ever need to get the properties for 1 car, but as soon as you expect multiple entries in your database, don't use a remote operation to query the schema, do use a caching client.

The sample application

1) What it does

The sample application uses the generated assemblies to create a cached CarData schema.
The application iterates over the schema's CarHasProperties relation and shows the contents to the user.
Has an interface that lets you call the get, set and remove operations on a CarData schema object.

2) Using the sample application

Open the sample application solution and check that the references are correct.
Run the schema server and check that it has connected as a server and is serving.
Run the client application. If a server is not present you should get a monitor form telling you this.
Create some entries in the CarHasProperties relation by entering a VIN, selecting a model and clicking on 'Create New'
Select one of the entries from the list view and verify that you get the same data when you click 'Get selected' properties.
Select one of the entries and click on Remove selected. The removed entry should no longer appear in the list view.
See the server's command window and review the history of actions.

What's next?

With the help of the client application we can test the schema server implementation as well as finding possible errors in the definition of the data model.