Package com.tailf.dp

Class Dp

Object
com.tailf.dp.Dp
Direct Known Subclasses:
NcsDp
public class Dp extends Object
This class implements the Data Provider API (DP). The purpose of this class library is to provide callback hooks so that user-written code can be invoked to perform various tasks.

NOTE: For NCS users the Dp class should not be used directly. Instead written callbacks must be packaged in a .jar file and referred to by the package-meta-data.xml file loaded by NCS.

The class library is also used to populate items in the YANG model which are not data or configuration items, such as statistics items.

The library consists of a number of API methods whose purpose is to install different callback methods at different points in the XML tree which is the representation of the device configuration. Read more about callpoints in tailf_yang_extensions(5).

There are different types of callbacks that can be registered to perform different tasks. Data callbacks are used to deliver data that is defined in the data model. If the data is statistics data, e.g. "config = false;" data, the callback objects only have to be able to respond to read requests, whereas if the data is configuration data, the callback objects must be able to also write data to persistent storage.

To register a data callback in ConfD, we can do: 

   // int port = Conf.PORT for ConfD or Conf.NCS_PORT for NCS
   Socket ctrl_socket= new Socket("127.0.0.1", port);
   final Dp dp = new Dp("server_daemon", ctrl_socket);
   dp.registerAnnotatedCallbacks(new SimpleTransCb());
   dp.registerAnnotatedCallbacks(new SimpleDataCb());
   dp.registerDone();
   Thread dpTh = new Thread(new Runnable() {
       public void run() {
           try {
               while (true) dp.read();
           } catch (Exception e) {
               e.printStackTrace();
               return;
           }
       }
   });
   dpTh.start();

To register a data callback in NCS , we must package the classes in the .jar file and place it in the package/my-package/private-jar directory and reference the annotated callbacks in the package/my-package/package-meta-data.xml: 

 <ncs-package xmlns="http://tail-f.com/ns/ncs-packages">
   <name>My-package</name>
  <package-version>1.0</package-version>
  <description>Abstraction test</description>
  <ncs-min-version>2.0</ncs-min-version>
  <component>
    <name>MyCallbacks</name>
    <callback>
      <java-class-name>
        com.example.mypackage.SimpleTransCb
      </java-class-name>
      <java-class-name>
        com.example.mypackage.SysDataCb
      </java-class-name>
    </callback>
  </component>
 </ncs-package>

Where the two classes MyTransCb and MyDataCb need to be annotated to indicate what capabilities they have. The following code show the annotation used ( Applies to both ConfD/NCS): 

 public class MyTransCb {

   @TransCallback(callType=TransCBType.INIT)
     public void init(DpTrans trans) throws DpCallbackException {
       trace("init(): userinfo= " + trans.getUserInfo());
     }

   @TransCallback(callType=TransCBType.FINISH)
     public void finish(DpTrans trans) throws DpCallbackException {
       trace("finish()");
     }
  }
  // And so on ...

The MyTransCb methods init , finish get called at the start and finish of each transactions. There exists a number of different possible entry points within the transaction. See @see TransCBType. And the data callbacks that need to be able to deliver the actual data. Given a data model that looks looks like: 


   container servers {
     config false;
     tailf:callpoint simplecp {
     }
     list server {
       key name;
       max-elements 64;
       leaf name {
         type string;
       }
       leaf ip {
         type inet:ip-address;
       }
       leaf port {
         type inet:port-number;
       }
       leaf macaddr {
         type tailf:hex-list;
       }
       leaf snmpref {
         type yang:object-identifier;
         mandatory true;
       }
       leaf prefixmask {
         type tailf:octet-list;
         mandatory true;
       }
     }
   }

The callback class to deliver the data could look like: 


 public class SimpleDataCb  {


     @DataCallback(callPoint="simplecp",
                        callType=DataCBType.ITERATOR)
     public Iterator<Object> iterator(DpTrans trans, ConfObject[] kp)
      throws DpCallbackException {
      return Foobar.iterator();
     }

     @DataCallback(callPoint="simplecp",
                        callType=DataCBType.GET_NEXT)
     public ConfKey getKey(DpTrans trans, ConfObject[] kp, Object obj)
      throws DpCallbackException {
      Server s = (Server) obj;
      return new ConfKey( new ConfObject[] { new ConfBuf(s.name) });
     }


     @DataCallback(callPoint="simplecp",
                        callType=DataCBType.GET_ELEM)
     public ConfValue getElem(DpTrans trans, ConfObject[] kp)
      throws DpCallbackException {
         return Foobar.get(kp);
     }

     @DataCallback(callPoint="simplecp",
                        callType=DataCBType.GET_OBJECT)
     public ConfValue[] getObject(DpTrans trans, ConfObject[] kp)
         throws DpCallbackException {
      String name = ((ConfKey) kp[0]).elementAt(0).toString();
      Server s = Foobar.findServer( name );
      if (s == null) return null;
      return getObject(trans, kp, s);
     }

     @DataCallback(callPoint="simplecp",
     callType=DataCBType.GET_NEXT_OBJECT)
     public ConfValue[] getObject(DpTrans trans, ConfObject[] kp, Object obj)
      throws DpCallbackException {
      Server s = (Server) obj;
      return new ConfValue[] {
          new ConfBuf(s.name),
          new ConfIPv4( s.addr),
          new ConfUInt16( s.port),
          new ConfHexList( s.macaddr ),
     }
 }

Dp uses ThreadPoolExecutor as managing its internal worker threads. Dp could be configured to prestart worker threads so the overhead of creating and starting threads is minimized.

Dp delivers a task (DpTrans,DpValidateTrans, DpActionTrans to worker threads when requests comes from controller socket. '

The worker threads could either wait for task to arrive to them or they could be started when needed. Dp provides constructor for setting various parameters to tune the behavior of threads pool

See Also:

  • Constructor Details

    • Dp

      public Dp(String name, Socket socket) throws IOException, ConfException
      This constructor will initialize the Dp class library and connect to ConfD/NCS on the provided control socket. The name parameter is used in various debug printouts and and is also used to uniquely identify the daemon. Since the ConfD/NCS daemon expects initialization within 5 seconds after a new socket is established this constructor should be called directly for a new socket. For instance: // int port = Conf.PORT for ConfD or Conf.NCS_PORT for NCS Dp dp = new Dp("xyz", new Socket("localhost", port));

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      Parameters:
      name - A name that uniquely identifies the daemon
      socket - A control socket connected to ConfD/NCS.
      Throws:
      DpException - Failed to initialize connection.
      DpCallbackException - Callback method failed.
      IOException - Failed to read from control socket.
      ConfException - Failed to decode or other internal failure.

    • Dp

      public Dp(String name, Socket ctrlSocket, boolean isNcs) throws IOException, ConfException
      This constructor will initialize the Dp class library and connect to ConfD/NCS on the provided control socket. The name parameter is used in various debug printouts and and is also used to uniquely identify the daemon. Since the ConfD/NCS daemon expects initialization within 5 seconds after a new socket is established this constructor should be called directly for a new socket.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file.

      The thread pool behavior is that it prestarts 5 worker threads and poolsize could max grow to 256 working threads. Keep alive time is set to 60 sec.

      The keepAlive time is the idle time of a thread before it is terminated. This value is only in effect when current thread is greater than corePoolSize. The default Queue is ArrayBlockingQueue with a queue size of 10. When more than 10 elements is in the queue then additional threads will be created.

      Parameters:
      name - A name that uniquely identifies the daemon
      ctrlSocket - The control socket connected to ConfD/NCS.
      isNcs - set to true if the data provider is managed by NcsDpMux
      Throws:
      DpException - Failed to initialize connection to ConfD/NCS.
      DpCallbackException - Callback method failed.
      IOException - Failed to read from control socket.
      ConfException - Failed to decode or other internal failure.

    • Dp

      public Dp(String name, Socket ctrlSocket, boolean isNcs, int minThreadPoolSize, int maxThreadPoolSize, long keepAliveTime, TimeUnit unit, BlockingQueue<Runnable> queue, boolean prestartCoreThreads) throws IOException, ConfException
      This constructor will initialize the Dp class library and connect to ConfD/NCS on the provided control socket. The name parameter is used in various debug printouts and and is also used to uniquely identify the daemon. Since the ConfD/NCS daemon expects initialization within 5 seconds after a new socket is established this constructor should be called directly for a new socket.

      If encrypted communication towards ConfD/NCS is desired, an environment variable "CONFD_IPC_ACCESS_FILE" or "NCS_IPC_ACCESS_FILE" need to be set. This variable is expected to point to a file containing a secret salt. example: export CONFD_IPC_ACCESS_FILE=./secret_file.txt An alternative to the environment variable is to set an java system property with the same name pointing to the file. Various parameters for tuning the worker thread pool could be specified here. The thread pool behavior is that it prestarts minThreadPoolSize worker threads if prestartCoreThreads is set to true. The poolsize could max grow to maxThreadPoolSize threads. Keep alive time is set to keepAliveTime units time. The keepAlive time is the idle time of a thread before it is terminated. This value is only in effect when current thread is greater than corePoolSize. The queue could be specified as bounded or not bounded which will interact with the poolsize.

      Parameters:
      name - A name that uniquely identifies the daemon
      ctrlSocket - The control socket connected to ConfD/NCS.
      isNcs - set to true if the data provider is managed by NcsDpMux
      minThreadPoolSize - Minimum worker thread in the worker pool
      maxThreadPoolSize - Maximum worker thread in the worker pool. This parameter works only when queue is bounded
      keepAliveTime - idle time for a thread before it is terminated
      unit - keepAlive units time
      queue - Queue that holds tasks. The use of this queue interacts with pool sizing.
      Throws:
      DpException - Failed to initialize connection to ConfD/NCS.
      DpCallbackException - Callback method failed.
      IOException - Failed to read from control socket.
      ConfException - Failed to decode or other internal failure.

  • Method Details

    • getDaemonId

      public int getDaemonId()
      The daemon identifier (assigned by ConfD/NCS).
      Returns:
      int daemon identifier

    • getCtrlSocket

      public Socket getCtrlSocket()
      The control socket which is connected to ConfD/NCS.
      Returns:
      Socket the control socket

    • setExceptionReporter

      public void setExceptionReporter(DpExceptionReporter exReporter)

    • getExceptionReporter

      public DpExceptionReporter getExceptionReporter()

    • registerDone

      public void registerDone() throws DpException
      When we have registered all the callbacks for a daemon we must call this function to synchronize with ConfD/NCS. No callbacks will be invoked until it has been called, and after the call, no further registrations are allowed.
      Throws:
      DpException - Failed with registerDone()

    • registerAnnotatedMountedCbs

      public void registerAnnotatedMountedCbs(DpMountIdInterface MountIdMethod, Object obj) throws DpException
      Throws:
      DpException

    • reRegisterAnnotatedMountedCbs

      public void reRegisterAnnotatedMountedCbs(DpMountIdInterface MountIdMethod, Object obj) throws DpException
      Throws:
      DpException

    • registerAnnotatedCallbacks

      public void registerAnnotatedCallbacks(Object obj) throws DpException
      All Data, Trans, Action, Validate, TransValidate and DB callbacks are registered using this method. The callback is any class having annotated callback methods. All annotated methods with correct signature are registered. The method name is arbitrary.

      Example of a DataCallback: 

       final class cbDataDemo {
    @DataCallback(callPoint="abc", callType=DataCBType.ITERATOR)
    public Iterator<Object> abc(DpTrans trans, ConfObject[] kp) {
        // Change this to the real implementation
        return null;
    }

    @DataCallback(callPoint="abc", callType=DataCBType.GET_NEXT)
    public ConfKey getKey(DpTrans trans, ConfObject[] kp, Object obj) {
        // Change this to the real implementation
        return null;
    }
    // And so on ...
 }

      The respective annotations are

      • @DataCallback
      • @TransCallback
      • @ActionCallback
      • @ValidateCallback
      • @TransValidateCallback
      • @DBCallback
      • @AuthCallback
      • @ServiceCallback

      The callType defines the callback method and each annotation has an Enum of legal values

      Parameters:
      obj - object to register as callback
      Throws:
      DpException

    • registerAnnotatedCallbacks

      public void registerAnnotatedCallbacks(String mountId, Object obj) throws DpException
      Throws:
      DpException

    • reRegisterAnnotatedCallbacks

      public void reRegisterAnnotatedCallbacks(Object obj) throws DpException
      reRegisters an existing callback. This implies that the current callback is exchanged If the current callback is not existing this is an noop
      Parameters:
      obj -
      Throws:
      DpException

    • reRegisterAnnotatedCallbacks

      public void reRegisterAnnotatedCallbacks(String mountId, Object obj) throws DpException
      Throws:
      DpException

    • registerAnnotatedRangeActionCallbacks

      public void registerAnnotatedRangeActionCallbacks(Object obj, ConfValue[] lower, ConfValue[] higher, ConfPath path) throws DpException
      Throws:
      DpException

    • reRegisterAnnotatedRangeActionCallbacks

      public void reRegisterAnnotatedRangeActionCallbacks(Object obj) throws DpException
      reRegisters an existing callback. This implies that the current callback is exchanged If the current callback is not existing this is an noop Note that the range cannot be changed and can therefore not be supplied in this call
      Parameters:
      obj -
      Throws:
      DpException

    • registerAnnotatedRangeDataCallbacks

      public void registerAnnotatedRangeDataCallbacks(Object obj, ConfValue[] lower, ConfValue[] higher, ConfPath path) throws DpException
      DataCallbacks can be registered for a range of values using this method
      Parameters:
      obj - object to register as callback
      lower - Array of lower bound key values
      higher - Array of higher bound key values
      path - A path
      Throws:
      DpException - Failed to register range data callback.

    • reRegisterAnnotatedRangeDataCallbacks

      public void reRegisterAnnotatedRangeDataCallbacks(Object obj) throws DpException
      reRegisters an existing callback. This implies that the current callback is exchanged If the current callback is not existing this is an noop Note that the range cannot be changed and can therefore not be supplied in this call
      Parameters:
      obj -
      Throws:
      DpException

    • read

      public void read() throws IOException, ConfException
      Receives data on the control socket which is connected to ConfD/NCS. Performs a blocking read. If a socket timeout value has been configured for the control socket, this method will (eventually) throw a SocketTimeoutException which the caller must handle.
      Throws:
      ConfException - Failed to decode.
      SocketTimeoutException - The control socket timed out.
      IOException - Failed to read from control socket.

    • getUserInfo

      public DpUserInfo getUserInfo(int usid)
      Retrieves the user information.
      Parameters:
      usid - User identifier

    • getNsList

      public ArrayList<ConfNamespace> getNsList()
      Get a list of the installed namespaces. The namespace list is needed, for example, when creating an object ref.

    • getWorkerPool

      public ThreadPoolExecutor getWorkerPool()
      Get current WorkerThreadPool
      Returns:
      WorkerThreadPool

    • setNumFreeWorkerSockets

      public void setNumFreeWorkerSockets(int numSockets)
      This method is used to control the number of workersockets that should be keept open for reuse. This can be used for tuning purposes, normally this should not be necessary. The default number of open sockets are 4. Negative values for numSockets are threated as 0.
      Parameters:
      numSockets - number of sockets.

    • createNotifStream

      public DpNotifStream createNotifStream(String name) throws ConfException, IOException
      Creates (and registers) a notifications stream with ConfD/NCS. This can be used for sending notifications to ConfD/NCS.
      Parameters:
      name - A name that uniquely identifies the notification stream
      Throws:
      DpCallbackException - Callback method failed.
      IOException - Failed to read from notification socket.
      ConfException - Failed to decode or other internal failure.
      See Also:

    • createNotifStream

      public DpNotifStream createNotifStream(String name, DpNotifReplayCallback replayCb) throws ConfException, IOException
      Creates (and registers) a notifications stream with ConfD/NCS. This can be used for sending notifications to ConfD/NCS.
      Parameters:
      name - A name that uniquely identifies the notification stream
      replayCb - A callback that implements 'replay' functionality. (optional)
      Throws:
      DpCallbackException - Callback method failed.
      IOException - Failed to read from notification socket.
      ConfException - Failed to decode or other internal failure.
      See Also:

    • createNotifStream

      public DpNotifStream createNotifStream(String name, DpNotifReplayCallback replayCb, Socket socket) throws ConfException, IOException
      Creates (and registers) a notifications stream with ConfD/NCS. This can be used for sending notifications to ConfD/NCS.
      Parameters:
      name - A name that uniquely identifies the notification stream
      replayCb - A callback that implements 'replay' functionality. (optional)
      socket - A worker socket to send notification on (optional)
      Throws:
      DpCallbackException - Callback method failed.
      IOException - Failed to read from notification socket.
      ConfException - Failed to decode or other internal failure.
      See Also:

    • createSnmpNotifier

      public DpSnmpNotifier createSnmpNotifier(String name, String context_name) throws ConfException, IOException
      Creates (and registers) a SNMP Notifer @see DpSnmpNotifier.
      Parameters:
      name - a name uniquely identifying the SNMP notifier.
      context_name - the SNMP context.
      Throws:
      IOException - Failed to read from notification socket.
      ConfException - Failed to decode or other internal failure.
      See Also:

    • createSnmpNotifier

      public DpSnmpNotifier createSnmpNotifier(String notify_name, String context_name, Object inform_cb) throws ConfException, IOException
      Creates (and registers) a SNMP Notifier @see DpSnmpNotifier.
      Parameters:
      notify_name - a name uniquely identifying the SNMP notifier.
      context_name - the SNMP context.
      inform_cb - the callback to be called for Inform Responses.
      Throws:
      IOException - Failed to read from notification socket.
      ConfException - Failed to decode or other internal failure.
      See Also:

    • createSnmpNotifier

      public DpSnmpNotifier createSnmpNotifier(String notify_name, String context_name, Object inform_cb, Socket socket) throws ConfException, IOException
      Creates (and registers) a SNMP Notifier see DpSnmpNotifier.
      Parameters:
      notify_name - a name uniquely identifying the SNMP notifier.
      context_name - the SNMP context.
      inform_cb - the callback to be called for Inform Responses.
      socket - socket to be used by DpSnmpNotifier as worker socket.
      Throws:
      IOException - Failed to read from notification socket.
      ConfException - Failed to decode or other internal failure.
      See Also:

    • closeAllWorkerSockets

      public void closeAllWorkerSockets()

    • shutDownThreadPool

      public void shutDownThreadPool()
      Initiates an orderly shutdown in which previously transactions are executed, but no new transactions will be accepted.

    • shutDownThreadPoolNow

      public int shutDownThreadPoolNow()
      Attempts to stop all actively executing transactions, halts the processing of waiting transactions, and returns number of the tasks that were awaiting execution.
      Returns:
      - Number of awaiting transactions that was not executed.

    • getErrorVerbosity

      public ErrorVerbosity getErrorVerbosity()
      Get the local verbosity level for reported errors If this verbosity is null the the default level governs the error verbosity of this Dp
      Returns:
      the current errorVerbosity for this Dp

    • setErrorVerbosity

      public void setErrorVerbosity(ErrorVerbosity verbosity)
      set the local verbosity level for reported errors If this verbosity is set to null the the default level governs the error verbosity of this Dp
      Parameters:
      verbosity -

    • getErrorMessageFormatter

      public ErrorMessageFormatter getErrorMessageFormatter()
      Return the errorMessageFormatter for this Dp.
      Returns:
      the ErrorMessageFormatter for this Dp.

    • getServicePointMaapi

      public Maapi getServicePointMaapi(DpTrans trans) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • getServicePointMaapi

      public Maapi getServicePointMaapi() throws IOException, ConfException
      Throws:
      IOException
      ConfException