Appendix 11 - Custom Discovery Job

Instead of following days 4 and 5 of this tutorial, it is possible for a developer to create his or her own job for device and/or point discovery. This will likely take some more effort than it would to just follow the instructions for days 4 and 5 of this tutorial. However, the discovery process as described in days 4 and 5 is designed to be a quot;One-size-fits-all" discovery process. Although it should be possible to the discovery process for any driver following days 4 and 5 of this tutorial, for some drivers it might seem quite awkward to implement a discovery according to days 4 and 5 of this tutorial.

Advanced Niagara AX developers may have had some exposure to the BJob or BSimpleJob classes from the core, Niagara AX framework. Behind-the-scenes, the processes for day 4 and 5 of this tutorial implement a Niagara AX job. Basically, a Niagara AX job is a runnable class that runs in the station-side (on the server which is probably a Jace or Web Supervisor). This special, runnable class can report progress back to the graphical user interface on the Workbench (on the client which is probably running either as stand-alone Workbench or in as a Java applet in a Web Browser).

The remainder of this appendix describes how to replace the default discovery job that is used by days 4 and 5 of this tutorial with a developer's own discovery job. This will give the developer much more freedom at the cost of extra development effort on his or her part.

Create a class that extends BDdfAutoDiscoveryJob
Override the 'autoLearn' method.
Send out any communications necessary
- Goal: Gather one or more discovery leaves
- Add them either as children of the job itself or as children of the job's discovery hosts's discoveryFolder (if the discovery leaves should persist in between visits to the user interface manager )
Open the discovery preferences structure (either the device discovery preferences or the point discovery preferences structure for your driver)
- Override the getDiscoverLeafType method and return the TYPE of the discovery leaves for this job.
- Override the 'getNeedsJob' method and return true.
Open the component that will be hosting the discovery (either the driver's network for device discovery or point device extension for point discovery)
- Redefine the 'discoveryPreferences' property and make the default be an instance of your driver's device or point discovery preferences structure.
- Override the 'doSubmitDiscoveryJob' method to submit an instance of the class that you were just instructed to create (the class that extends BDdfAutoDiscoveryJob)

TIPS:

From the 'autoLearn' method or any method that is called by the 'autoLearn' method, periodically check if the getStatus() == BJobStatus.canceling and if so, throw a JobCancelException to rewind the stack and thus, stop the job gracefully.

Consider one of the following philosophies as a guide for 'when/where' to gather discovery children:

Synchronous request-response transactions

Make the discovery request implement BIDdfCustomRequest.

Doing this causes the DDF to make callbacks to the request when the respones is received or timed out.

The request should cache the response and provide a getter method to access the response.

From the 'autoLearn' logic, pass an instance of a discovery request to DdfRequestUtil.communicateSync.

The 'communicateSync' method places the request on the communicator queue and then blocks the calling thread until either a response is received or timed out.

After the call to 'communicateSync' returns, call the getter method on the request that you designed to return the cached response.

Construct discovery leaf objects and populate their property values appropriately based on the data in the responses.

Add discovery leaves as children of either the job or the job's discovery host's discovery folder.

Asynchronous request-resposnes

Design the discovery request such that the job can be passed to the request.

Make the discovery request implement BIDdfCustomRequest.

Doing this causes the DDF to make callbacks to the request when the response is received or timed out.
From the 'processResponse' callback (not to be confused with theprocessReceivecallback), add discovery leaves with the appropriate property values as reported in the response data. Add these as children of either the job or the job's discovery host's discovery folder.

From the 'autoLearn' logic, queue up as many instances of the request to the communicator (as many instances as necessary) by simply calling getDiscoveryHost().getDdfCommunicator().communicate(req).
For the very last request, call DdfRequestUtil.communicateSync(req). This will cause the job thread to block until the response or timeout of the the very last request. This is safe because the communicator processes all requests on a FIFO queue.