Chapter 12 - Create a Proxy Extension For Your Driver

As discussed in the introduction before the first day's lesson, the Niagara AX framework uses something called a driver control point to represent a data value that is inside an external unit of equipment. It is now time to take this discussion one step forward.

Niagara AX control points have a frozen property on them named proxyExt. Drivers define the external behavior of Niagara AX control points by defining a proxy extension component. The developer driver framework automatically places an instance of your driver's proxy extension onto Niagara AX control point components, as necessary, for your convenience. Therefore, all you need to do is follow this procedure to make this happen automatically:

While following the examples in this chapter, please replace the text jarFileName, yourDriver and yourCompany as previously described in the Preparation section):

Make a Java class that extends BDdfProxyExt. Name it BYourDriverProxyExt. Create this in a package named com.yourCompany.yourDriver.point. Also add an empty slotomatic comment, with an empty properties section immediately after the opening brace for the class declaration.

To do this, create a text file named BYourDriverProxyExt.java in the jarFileName/src/com/yourCompany/yourDriver/point folder. Inside the text file, start with the following text:

package com.yourCompany.yourDriver.point;

import javax.baja.sys.*;

import com.tridium.ddf.point.*;
import com.tridium.ddf.identify.*;

import com.yourCompany.yourDriver.identify.*;


public class BYourDriverProxyExt
  extends BDdfProxyExt
{
  /*-
  class BYourDriverProxyExt
  {
    properties
    {
    }
  }
  -*/

  public Type getDeviceExtType()
  { // You will need to return BYourDriverPointDeviceExt
    // After you create it in a subsequent chapter. For
    // Now, please return null to satisfy the compiler.
    return null;
  }
}

NOTE: BDdfProxyExt, the ancestor of BYourDriverProxyExt, has already defined a property called readParameters and a property called pointId. You need to redefine those two properties and change the default value to be an instance of the corresponding classes in your driver.
In one of the previous chapters of today's lesson, we showed you how to create the read parameters structure. We also explained that the read parameters structure tells an instance of your driver's read request how to construct the byte array that it must return from its toByteArray method (function).
Also, in a previous chapter of today's lesson, we showed you how to create the read response but had you simply return null from the parseReadValue method of your read response. In a subsequent chapter of today's lesson, we will show you how to finish defining the parseReadValue method of your read response. It is time that we give you a little more explanation about that.
Please recall that the parseReadValue method is passed an instance of IDdfReadable. All proxy extensions in the developer driver framework implement this Java interface. In fact, the developer driver framework will make one or more successive calls into your read response's parseReadValue method (function). The developer driver framework will call this method on your response one or more times, once for each driver control point that is under the same device from your driver and that shares the equivalent read parameters structure. The framework will pass the proxy extension itself, cast as an IDdfReadable, into the parseReadValue method (function) of your read response.

Redefine the readParameters property to use your driver's read parameters structure.

Declare an instance of your driver's read parameters as the default value for the readParameters property:

  /*-
  class BYourDriverProxyExt
  {
    properties
    {
       readParameters : BDdfIdParams
         -- This hooks your driver's read parameters structure into the
         -- proxy extension that is placed on control points that are
         -- under devices in your driver. The read parameter's structure
         -- tells the dev driver framework which read request to use to
         -- read the control point. It also tells your read request's
         -- toByteArray method how to construct the bytes for the request.
         default{[new BYourDriverReadParams()]}
         slotfacets{[MGR_INCLUDE]}
    }
  }
  -*/

Redefine the pointId property to use the point id class from your driver (to be created soon).

Even though you have not yet created it, we will show you how to create the point id in a subsequent chapter of today's lesson.

  /*-
  class BYourDriverProxyExt
  {
    properties
    {
       readParameters : BDdfIdParams
         -- This hooks your driver's read parameters structure into the
         -- proxy extension that is placed on control points that are
         -- under devices in your driver. The read parameter's structure
         -- tells the dev driver framework which read request to use to
         -- read the control point. It also tells your read request's
         -- toByteArray method how to construct the bytes for the request.
         default{[new BYourDriverReadParams()]}
         slotfacets{[MGR_INCLUDE]}

       pointId : BDdfIdParams
         -- This tells your read response's parseReadValue method how to
         -- extract the data value for a particular control point.
         default{[new BYourDriverPointId()]}
         slotfacets{[MGR_INCLUDE]}
    }
  }
  -*/

NOTE: Providing the slotfacet of MGR_INCLUDE on each of these structured properties will cause any of their properties that are flagged with MGR_INCLUDE to automatically appear in your point manager for your driver.

Run slotomatic with the -mi switch and resolve any slotomatic compiler errors. Do not perform an actual build on your driver yet (this class is not yet ready to be fully compiled).
A couple more classes are required before you will be able to successfully perform a full build on your driver. One of these is the point id, which we mentioned briefly in this chapter. The other is the point device extension, which is very simple to create. Next, we will show you how to create these both. After that, we will have you finish creating your proxy extension.