Chapter 27 - Create Your Point Discovery Parameters

NOTE: This class is analogous to your driver's read parameters, write parameters, and device discovery parameters classes that you created during the previous day's lessons. Just as you may have been able to use your driver's device id as the device discovery parameters class, you may likewise be able to use your driver's read parameters structure as the point discovery parameters structure.

DISCUSSION: Some protocols feature a message that can be sent to the field-device to ask the field-device for a list of data points. In that case, the field-devices sometimes return a list of information about all data points in the device. Alternatively, the request might ask the device for a particular group of data points that fall into a particular category or classification. If your driver's protocol supports such a message, then you will create five new classes today. If not, then you will create two new classes and modify your driver's read parameters structure, read request, and read response to also serve in the point discovery process. The latter scenario is similar to how the previously day's lesson instructed you to configure your device id, ping request, etc. to also serve the device discovery mechanism.

Please follow one of the next two paths (A or B, but not both).

A. If your driver's protocol features a message that can be sent to the field-device to ask it for a list data points:

Determine what information the request's byte array will need.

Create a class named BYourDriverPointDiscoverParams that extends BDdfDiscoveryParams in the package com.yourCompany.yourDriver.identify.

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

package com.yourCompany.yourDriver.identify;

import com.tridium.ddf.identify.*;
import javax.baja.sys.*;

import com.yourCompany.yourDriver.comm.req.*;
import com.testCompany.yourDriver.discover.*;


public class BYourDriverPointDiscoverParams
  extends BDdfDiscoverParams
{
  /*-
  class BYourDriverPointDiscoverParams
  {
    properties
    {
    }
  }
  -*/
}

Based on your driver's protocol document, please be prepared to add properties to the slotomatic statement to help you construct the byte array in the point discovery request (you will create the point discovery request in the next chapter). You may return to this class and add properties to the slotomatic statement for any data values you require to construct the byte array for your point discovery request (to be created in the next chapter).

Define the getFirst, getLast, getNext, and isAfter methods. These are essential and allow the developer driver auto discovery process to automatically loop through all possible combinations of your discovery parameters.

NOTE: Yesterday's lesson explained how to do this for the device discovery process.

getFirst

The getFirst method should return an instance of BYourDriverPointDiscoverParams that represents the data that would be placed in the protocol request to request information about the first data point or series of data points. If your protocol has no way of identifying a definite first data point then you will need to be creative here and return an instance of BYourDriverPointDiscoverParams with all properties set to special values, that you will determine, such as Integer.MIN_VALUE for int properties.

getLast

The getLast method should return an instance of BYourDriverPointDiscoverParams that represents the data in the protocol request that would request information about the last device or series of devices. This might not be possible to accurately define for some protocols. If your protocol does not have a way of identifying the last series of data points, then you will need to be creative here and return an instance of BYourDriverPointDiscoverParams with all properties set to special values, that you will create, such as Integer.MAX_VALUE for int properties.

getNext

The getNext method should return an instance of BYourDriverPointDiscoverParams that represents the data in the protocol request that would request the next data point or series of data points, with respect to the particular instance of BYourDriverPointDiscoverParams. This method should review the values of some or all of the properties that you add to BYourDriverPointDiscoverParams. This method should return a new instance of BYourDriverPointDiscoverParams whose property values are incremented in such a way that the new instance would represent the data needed in the toByteArray method of the point discovery request in order to ask the field-device for information about the next data point or set of data points.

isAfter

The isAfter method will be passed an instance of BYourDriverPointDiscoverParams. You should review the property values of the given instance of BYourDriverPointDiscoverParams and return true if the current instance would request information about a data point or series of data points that would be after the data point or series of data points that the given instance of BYourDriverPointDiscoverParams would identify. If the current instance represents a data point or series of data points that are before or equal to the given instance, then this method should return false.

We understand that this can be a bit tricky, since the definitions of first, last, next, and after can be somewhat vague in some protocols. Please feel free to skip ahead and revisit this later if you wish.

As a reference, please see the sample getFirst, getLast, getNext, and isAfter methods that are illustrated below, for part B.

Define the getDiscoverRequestType method and make it return an instance of your driver's point discovery request. You will create the point discovery request later during today's lesson.
public Type getDiscoverRequestType() { return BYourDriverDiscoveryRequest.TYPE; }

Define the getDiscoveryLeafType method and make it return a reference to your driver's point discovery leafTYPE. The point discovery leaf will be created in a subsequent chapter of today's lesson.

  /**
   * This tells the developer driver framework that
   * instances of BYourDriverDiscoveryLeaf will be
   * placed into the discovery list of the point
   * manager to represent each data point that the
   * driver discovers.
   */
  public Type getDiscoveryLeafType()
  {
    return BYourDriverPointDiscoveryLeaf.TYPE;
  }

B. If your driver's protocol does not feature a message that can be sent to the field-device to ask it for a list of data points then you will modify your driver's read parameters to also serve as the point discover parameters.

Open the BYourDriverReadParams.java file from day 2 of this tutorial.
Modify the class declaration statement and declare that BYourDriverReadParams implements BIDdfDiscoverParams.

public class BYourDriverReadParams
  extends BDdfReadParams
  implements BIDdfDiscoverParams
{
  ...
}

Your driver's read parameters structure, acting also as the point discover params structure, needs to satisfy the BIDdfDiscoverParams interface and define the getFirst, getLast, getNext, and isAfter methods in order to allow the developer driver auto discovery process to automatically loop through all possible combinations of your discovery parameters.

Please review the discussion concerning these methods as described in part A (in this chapter - above)

EXAMPLE: In the hypothetical protocol that we used back during day 2 of this tutorial, the read request retrieves data point values by asking the hypothetical field device for the values of all points of a certain type and direction (for example, analog inputs, analog outputs, digital inputs, or digital outputs).
In that scenario, the getFirst method would return an instance of BYourDriverReadParams with a type string of analog and a direction string of inputs. The getNext method would return an instance of BYourDriverReadParams with a type string of analog but with a direction string of outputs. That instance's getNext method would return an instance of BYourDriverReadParams with a type string of digital and a direction string of inputs. That instance's getNext method would return an instance of BYourDriverReadParams with a type string of digital but with a direction string of outputs. Finally, the getLast method will return an instance of BYourDriverReadParams with a type string of digital and a direction string of outputs.

NOTE: In this example, we have imposed our own ordering for all of the possible combinations of the sample read parameters structure.

Please define your own version of these methods using the following example as a guide.

NOTE: Your driver's read parameters structure also needs to import packages:

javax.baja.registry.*
com.tridium.ddf.discover.*
com.yourCompany.yourDriver.discover.*


package com.yourCompany.yourDriver.identify;

import javax.baja.sys.*;
import javax.baja.registry.*;

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

import com.yourCompany.yourDriver.comm.req.*;
import com.yourCompany.yourDriver.discover.*;

public class BYourDriverReadParams
  extends BDdfReadParams
  implements BIDdfDiscoverParams
{
  ...
  ...
  ...

  /**
   * Niagara AX requires a public, empty constructor, so that it can perform
   * Its own introspection operations.
   */
  public BYourDriverReadParams(){}
  /**
   * This constructor is for our own convenience in the methods getFirst,
   * getNext, etc.
   */
  public BYourDriverReadParams(String typeString, String direction)
  {
    setTypeString(typeString);
    setDirection(direction);
  }

  public BIDdfDiscoverParams getFirst()
  {
    return new BYourDriverReadParams("analog","inputs");
  }

  public BIDdfDiscoverParams getLast()
  {
    return new BYourDriverReadParams("digital","outputs");
  }

  public BIDdfDiscoverParams getNext()
  { // In all truth, our typeString and direction properties essentially
    // Could be combined into a single enumeration. Let's at least treat
    // It that was to help make this method simple.
    switch (getConvenientNumber()) // getConvenientNumber is a private
    {                              // method that we created below
      case 0:  // Current = analog inputs   Next = analog outputs
        return new BYourDriverReadParams("analog","outputs");
      case 1:  // Current = analog outputs  Next = digital inputs
        return new BYourDriverReadParams("digital","inputs");
      case 2:  // Current = digital inputs  Next = digital outputs
        return new BYourDriverReadParams("digital","outputs");
      //case 3:
      default: // Current = digital outputs Next = analog inputs
        return new BYourDriverReadParams("analog","inputs");
    }
  }

  public boolean isAfter(BIDdfDiscoverParams anotherId)
  { // In all truth, our typeString and direction properties essentially
    // Could be combined into a single enumeration. Let's at least treat
    // It that was to help make this method simple.
    return this.getConvenientNumber() > ((BYourDriverReadParams)anotherId).getConvenientNumber();
  }

  /**
   * We created up this method to help with the isAfter and getNext methods.
   *
   * This method allows us to effectively enumerate all possible, reasonable
   * instances of this class.
   */
  private int getConvenientNumber()
  { // This creates an "ordering" on all reasonable instances of this class.
    if (getTypeString().equals("analog") &&
        getDirection().equals("inputs"))
    {
      return 0;
    }
    else if (getTypeString().equals("analog") &&
             getDirection().equals("outputs"))
    {
      return 1;
    }
    else if (getTypeString().equals("digital") &&
             getDirection().equals("inputs"))
    {
      return 2;
    }
    else // "digital outputs" or anything else (invalid as it
         // might be)
    {
      return 3;
    }
  }


  ...
  ...
  ...
}

Define the getDiscoverRequestType method and make it return a reference to your driver's read request TYPE.
REMINDER: In this scenario, your driver's read request will also serve during the point discovery process.
/** * The read request will also serve during the * point discovery process. */ public Type getDiscoverRequestType() { return BYourDriverReadRequest.TYPE; }
Define the getDiscoverRequestTypes method and make it return an array of size one, with the one element being a reference to your driver's read request TYPE.
REMINDER: In this scenario, your driver's read request will also serve during the point discovery process.
public Type[] getDiscoverRequestTypes() { return new Type[]{BYourDriverReadRequest.TYPE}; }

Define the getDiscoveryLeafType method and make it return a reference to your driver's point discovery leafTYPE. The point discovery leaf will be created in a subsequent chapter of today's lesson.

  /**
   * This tells the developer driver framework that
   * instances of BYourDriverDiscoveryLeaf will be
   * placed into the discovery list of the point
   * manager to represent each data point that the
   * driver discovers.
   */
  public Type getDiscoveryLeafType()
  {
    return BYourDriverPointDiscoveryLeaf.TYPE;
  }