Documentation - Use Case - Leveraging a version's proxy in a client

Use Case: Leveraging a version's proxy in a client

Abstract

For every version of a given database class, DataClass generates a proxy object based on the design of that version. At a minimum, a proxy wraps up a connection and ensures that clients operating through the proxy are connecting to instances of a database class that have been upgraded to the exact right version. The amount of interface an behavior available in this proxy. The proxy class has a tree of objects that allow easy binding of design element physical names into dynamically-generated SQL strings. It also has a method on it for each procedure design element. If done right, a database instance can look like "just another object."

Body

The point of DataClass is to empower developers by automating anything that can be done by a mindless machine. One such thing is gluing a client and a database together. That's not to say that DataClass can generate every query that might ever be run against any database that might be developed. Instead, it gives you to the tools to spend more time developing queries and less time typing the same using(var command = connection.CreateCommand()) clause over and over again.

Let's start with a database that has a reasonably interesting design as an example:

You can click on keywords and concepts in blue.

database KindOfInteresting
{
  types int as integer;
  
  version 1.0 : initialized
  {
    design
    {
      protected table Points
      {
        public column X ("x") with DataType = type(int);
        public column Y ("y") with DataType = type(int);
      }
      
      public procedure GetXIntercepts ("dbp_GetXIntercepts")
      {
        public parameter InterceptPoint ("@x") : Points.X;
        public parameter Count ("@c") with DataType = type(int);
        public result ReturnRows : Points;
      }
    }
    
    construction
    {
      step sql { CREATE TABLE $[Points.Declaration]; }
      
      // SQL Server...
      in context GetXIntercepts
      {
        step sql
        {
CREATE PROCEDURE $[GetXIntercepts]
  $[InterceptPoint.Declaration],
  $[Count.Declaration]
AS
  SET $[Count] = (SELECT COUNT(*) FROM $[Points] WHERE $[Points.X] = $[InterceptPoint]);
  SELECT $[Points.X], $[Points.Y] FROM $[Points] WHERE $[Points.X] = $[InterceptPoint];
        }
      }
    }
  }
}

KindOfInteresting.dbc

Having a fully described stored procedure - GetXIntercepts - will cause DataClass to add to the version 1.0 proxy a method named GetXIntercepts. Because the stored procedure has a parameter named InterceptPoint, the GetXIntercepts proxy method will have an InterceptPoint parameter with the appropriate .NET and/or Java type. Because there is a result design element in the GetXIntercepts procedure, the return value will of the method will have a property named ReturnRows which will be an array of rows with X and Y values. The return value will also have a property for the Count parameter.

As a result, it is very easy to write a client that uses this database:

public class ASimpleClient
{
  private readonly KindOfInteresting.Design.Current.Proxy proxy;
  private ASimpleClient(IDbConnection connection)
  {
    // Won't let me connect to a database of the wrong version
    proxy = KindOfInteresting.Design.Current.Proxy.GetInstance(connection);
  }
  
  public int AverageYAtX(int x)
  {
    var result = proxy.GetXIntercepts(x);
    
    var total = 0l;
    
    foreach (var row in result.ReturnRows)
    {
      total += row.Y;
    }
    
    return total / result.Count;
  }
}

Client.cs

The client is pretty simple and could be a lot simpler. As we add new versions to KindOfInteresting, they will inherit the design elements of their predecessors. Clients which couple to proxy structures will continue to compile and operate correctly until a breaking change is made in KindOfInteresting's design. If course, if we have chosen to couple the client directly to a specific version, they would be unable to connect to databases of a different version but otherwise immune to the effects of future changes.

DataClass

Use Case: Leveraging a version's proxy in a client

Abstract

Body

Related Use Cases

Related Concepts

Related Keywords

Other Actions