Package com.tailf.maapi

Class Maapi

Object
com.tailf.maapi.Maapi
All Implemented Interfaces:
Closeable, AutoCloseable
public class Maapi extends Object implements Closeable

This class implements the Management Agent API (MAAPI).

The purpose of the class is twofold:

  • MAAPI can be used to implement our own proprietary management agent.

  • We can also use Maapi to attach to already existing transactions, for example when we wish to implement semantic validation of data elements or implement a CLI wizard.

Example: 

 // int port = Conf.PORT for ConfD or Conf.NCS_PORT for NCS
 // Setup socket to server
 Socket s = new Socket("localhost", port);

 // Start MAAPI session for admin user, originating from localhost
 Maapi maapi = new Maapi(s);
 maapi.startUserSession("admin",
     "maapi",
     new String[] { "admin" },
     new SocketAddress(InetAddress.getLocalHost(), 0),
     MaapiUserSessionFlag.PROTO_TCP);

 // Start a read transaction towards the running configuration.
 int tid = maapi.startTrans(Conf.DB_RUNNING, Conf.MODE_READ);
 // Set the namespace for the upcoming data operations
 maapi.setNamespace(tid, "http://tail-f.com/test/mtest/1.0");
 // Read the maxLeaseTime setting in the running configuration.
 ConfObject r = maapi.getElem(tid, "/mtest/servers/server{www}/ip");
 // Done, the transaction and user session is automatically
 // ended when the socket is closed.
 s.close();

  • Field Details

    • IA_CLIENT_MAAPI

      public static final int IA_CLIENT_MAAPI
      See Also:

    • MAAPI_UPGRADE_KILL_ON_TIMEOUT

      public static final int MAAPI_UPGRADE_KILL_ON_TIMEOUT
      Flag to use in initUpgrade()
      See Also:

    • COMMIT_NCS_NO_REVISION_DROP

      public static final int COMMIT_NCS_NO_REVISION_DROP
      Flags to use in: applyTrans(int,boolean,int) prepareTrans(int,int)
      See Also:

    • COMMIT_NCS_NO_DEPLOY

      public static final int COMMIT_NCS_NO_DEPLOY
      See Also:

    • COMMIT_NCS_NO_NETWORKING

      public static final int COMMIT_NCS_NO_NETWORKING
      See Also:

    • COMMIT_NCS_NO_OUT_OF_SYNC_CHECK

      public static final int COMMIT_NCS_NO_OUT_OF_SYNC_CHECK
      See Also:

    • COMMIT_NCS_NO_OVERWRITE_WRITE_SET_ONLY

      public static final int COMMIT_NCS_NO_OVERWRITE_WRITE_SET_ONLY
      See Also:

    • COMMIT_NCS_USE_LSA

      public static final int COMMIT_NCS_USE_LSA
      See Also:

    • COMMIT_NCS_NO_LSA

      public static final int COMMIT_NCS_NO_LSA
      See Also:

    • COMMIT_NCS_RECONCILE_KEEP_NON_SERVICE_CONFIG

      public static final int COMMIT_NCS_RECONCILE_KEEP_NON_SERVICE_CONFIG
      See Also:

    • COMMIT_NCS_RECONCILE_DISCARD_NON_SERVICE_CONFIG

      public static final int COMMIT_NCS_RECONCILE_DISCARD_NON_SERVICE_CONFIG
      See Also:

    • COMMIT_NCS_RECONCILE_ATTACH_NON_SERVICE_CONFIG

      public static final int COMMIT_NCS_RECONCILE_ATTACH_NON_SERVICE_CONFIG
      See Also:

    • COMMIT_NCS_RECONCILE_DETACH_NON_SERVICE_CONFIG

      public static final int COMMIT_NCS_RECONCILE_DETACH_NON_SERVICE_CONFIG
      See Also:

    • COMMIT_NCS_CONFIRM_NETWORK_STATE

      public static final int COMMIT_NCS_CONFIRM_NETWORK_STATE
      See Also:

    • COMMIT_NCS_CONFIRM_NETWORK_STATE_RE_EVALUATE_POLICIES

      public static final int COMMIT_NCS_CONFIRM_NETWORK_STATE_RE_EVALUATE_POLICIES
      See Also:

    • COMMIT_NCS_NO_OVERWRITE_WRITE_AND_FULL_READ_SET

      public static final int COMMIT_NCS_NO_OVERWRITE_WRITE_AND_FULL_READ_SET
      See Also:

    • COMMIT_NCS_NO_OVERWRITE_WRITE_AND_SERVICE_READ_SET

      public static final int COMMIT_NCS_NO_OVERWRITE_WRITE_AND_SERVICE_READ_SET
      See Also:

  • Constructor Details

    • Maapi

      public Maapi(Socket socket) throws ConfException
      Creates a new instance of Maapi supplying a established open socket to ConfD/NCS 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 Maapi maapi = new Maapi(new Socket("localhost", port));

      When establishing a connection to ConfD/NCS the MaapiSchemas will be loaded once automatically by the library.

      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:
      socket - A socket connected to ConfD/NCS.
      Throws:
      ConfException - If ConfD/NCS refuses to establish connection the reason could be obtained through Throwable.getMessage()
      ConfException - signals problem connecting to ConfD/NCS

    • Maapi

      public Maapi(SocketAddress address) throws IOException, ConfException
      Creates a new instance of Maapi supplying an address to the ConfD/NCS server.

      When establishing a connection to ConfD/NCS the MaapiSchemas will be loaded once automatically by the library.

      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:
      address - An address to connect to
      Throws:
      ConfException - If ConfD/NCS refuses to establish connection the reason could be obtained through Throwable.getMessage()
      IOException - signals I/O exception when creating the underlying socket
      ConfException - signals problems creating the underlying socket or connecting to ConfD/NCS

  • Method Details

    • init

      public void init() throws ConfException
      Throws:
      ConfException

    • getNsList

      public ArrayList<ConfNamespace> getNsList()
      Get a list of the installed namespaces retrieved from the loaded MaapiSchemas. The underlying socket is not required to be open for this operation.
      Returns:
      list of namespaces

    • startUserSession

      public void startUserSession(String user, String context) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • startUserSession

      public void startUserSession(String user, String context, String[] groups) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • startUserSession

      public void startUserSession(String user, String context, String[] groups, SocketAddress source) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • startUserSession

      public void startUserSession(String user, String context, String[] groups, SocketAddress source, MaapiUserSessionFlag proto) throws IOException, ConfException
      Establish a new user session on this Maapi instance.

      Once we have created a Maapi communication instance, we must also establish a user session.

      It is up to the user of the Maapi class to authenticate users.

      Maapi can be used to to perform the actual authentication through a call to authenticate(String,String) but authentication may very well occur through some other external means.

      Thus, when we use this function to create a user session, we must provide all relevant information about the user. If we wish to execute read/write transactions over the MAAPI interface, we must first have an established user session.

      A user session corresponds to a NETCONF manager who has just established an authenticated SSH connection, but not yet sent any NETCONF commands on the SSH connection.

      The user string is the login name of the user. The user name is used when setting up the AAA environment for the session.

      The srcip address specifies from where did the session originate.

      The context parameter can be any string which is precisely the context string which will be used to authorize all data access through the AAA system. Each AAA rule has a context string which must match in order for a AAA rule to match. (See the AAA chapter in the User Guide).

      Using the string "system" for context has special significance:

      • The session is exempt from all max sessions limits in the configuration file.
      • There will be no authorization checks done by the AAA system.
      • The session is not logged in the audit log.
      • The session is not shown in 'confd --status' or 'ncs --status', nor 'show users' in CLI etc.
      • The session may be started already in start phase 0. (However read-write transactions can not be started until phase 1)
      Thus this can be useful e.g. when we need to create the user session for an "internal" transaction done by an application, without relation to a session from a northbound agent. Of course the implications of the above need to be carefully considered in each case.

      It is not possible to create new user sessions until the system has reached start phase 2 with the above exception of a session with the context set to "system".

      The photo parameter specifies the protocol used by the user for connecting to the device. Can be one of MaapiUserSessionFlag.PROTO_SSH, MaapiUserSessionFlag.PROTO_CONSOLE, MaapiUserSessionFlag.PROTO_TCP, and MaapiUserSessionFlag.PROTO_SSL

      Parameters:
      user - Login name of user
      context - The context string parameter stated discussed above.
      groups - An array of AAA groups that the user belongs to.
      source - source address where the user session originate
      proto - Protocol used by the user for connecting to the device..
      Throws:
      MaapiException - If ConfD/NCS could not create a new session based on the parameters. To get detailed message use Throwable.getMessage()
      IOException - signals I/O exception on the underlying socket
      ConfException

    • startUserSession

      @Deprecated public void startUserSession(String user, InetAddress source, String context, String[] groups, MaapiUserSessionFlag proto) throws IOException, ConfException
      Deprecated.
      Use startUserSession(String, String, String[], SocketAddress, MaapiUserSessionFlag) instead.
      Throws:
      IOException
      ConfException

    • startUserSession

      @Deprecated public void startUserSession(String user, InetAddress source, String context, String[] groups, MaapiUserSessionFlag proto, String vendor, String product, String version, String clientId) throws IOException, ConfException
      Deprecated.
      Use startUserSession(String, String, String[], SocketAddress, MaapiUserSessionFlag, String, String, String, String) instead.
      Throws:
      IOException
      ConfException

    • startUserSession

      public void startUserSession(String user, String context, String[] groups, SocketAddress source, MaapiUserSessionFlag proto, String vendor, String product, String version, String clientId) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • endUserSession

      public void endUserSession() throws IOException, ConfException
      Ends the current user session on this Maapi instance.

      If the Maapi socket is closed, the user session is automatically ended.

      Throws:
      MaapiException - If there is no current session on this Maapi instance
      IOException - Signals I/O exception on the underlying socket
      ConfException

    • killUserSession

      public void killUserSession(int usid) throws IOException, ConfException
      Ends another users session, effectively logging out that user.
      Parameters:
      usid - ID of session to terminate
      Throws:
      MaapiException - If the session with the ID did not exists
      IOException - Signals I/O exception on the underlying socket
      ConfException

    • getUserSession

      public MaapiUserSession getUserSession(int usid) throws IOException, ConfException
      Return a MaapiUserSession given by the usid.
      Parameters:
      usid - ID of session to retrieve
      Throws:
      MaapiException - If the user session with the given ID does not exits
      IOException - Signals I/O exception on the underlying socket
      ConfException

    • getUserSessions

      public int[] getUserSessions() throws IOException, ConfException
      Return all user sessions id's currently connected to ConfD/NCS.
      Throws:
      MaapiException - -
      IOException - Signals I/O exception on the underlying socket
      ConfException

    • getMyUserSession

      public int getMyUserSession() throws IOException, ConfException
      Returns the usid associated with this Maapi
      Throws:
      MaapiException - If no user session exists on this Maapi socket
      IOException - Signals some I/O exception on the underlying socket
      ConfException

    • getUserSessionIdentification

      public MaapiUserSessionId getUserSessionIdentification(int usid) throws ConfException, IOException
      This method can be used to retrieve additional identification information for a user session (if available - ie., if it has been provided by the northbound client).
      Parameters:
      usid - Session id
      Returns:
      A MaapiUserSessionId object with the fields vendor, product, version and clientId.
      Throws:
      ConfException
      IOException
      MaapiException

    • getUserSessionOpaque

      public String getUserSessionOpaque(int usid) throws ConfException, IOException
      If the user session has "opaque" information provided by the northbound client (see the -O option in confd_cli), the opaque information can be retrieved using this method.
      Parameters:
      usid - User session id
      Throws:
      ConfException
      IOException

    • setNextUserSessionId

      public void setNextUserSessionId(int usid) throws ConfException, IOException
      Set the user session id that will be assigned to the next user session started. The given value is silently forced to be in the range 100 .. 2^31-1. This function can be used to ensure that session ids for user sessions started by northbound agents or via MAAPI are unique across a ConfD/NSO restart.
      Parameters:
      usid - The session id to assign for the next user session
      Throws:
      ConfException
      IOException

    • validateToken

      public String[] validateToken(String token, InetAddress srcAddr, int srcPort, String context, MaapiUserSessionFlag proto) throws ConfException, IOException
      If external token validation (see /confdConfig/aaa/externalValidation) is in use, this method can be used to ask ConfD/NSO to validate such a token.
      Parameters:
      token - The token to validate
      srcAddr - source address
      srcPort - source port
      context - context
      proto - extra information passed to the token validation executable (see /confdConfig/aaa/externalValidation/includeExtra)
      Throws:
      ConfException
      IOException

    • startTrans

      public int startTrans(int dbname, int mode) throws IOException, ConfException
      Start a new transaction towards the specified database dbname with a transaction mode mode.

      The main purpose of MAAPI is to provide read and write access into the transaction manager. Regardless of whether data is kept in CDB or in some* (or several) external data bases, the same API is used to access data.

      ConfD/NCS acts as a mediator and multiplexes the different commands to the code which is responsible for each individual data element.

      This function creates a new transaction towards a specified data base. If successful, it returns a new transaction identifier, a tid which must be used as a parameter in most of the Maapi methods which manipulate the transaction.

      We will drive this transaction forward through the different states a transaction goes through. If an external database is used, and it has registered callback functions for the different transaction states, those callbacks will be called when we in MAAPI invoke the different MAAPI transaction manipulation functions. For example when we call startTrans the init callback will be invoked in all external databases. If data is kept in CDB, the system will handle everything internally.

      The parameter dbname is supplied using on of Conf.DB_STARTUP,Conf.DB_RUNNING,Conf.DB_CANDIDATE

      Transaction mode mode is supplied using Conf.MODE_READ, to start a read only transaction Conf.MODE_READ_WRITE to start a read write transaction.

      A read only transaction will incur less resource usage, thus if no writes will be done (e.g. the purpose of the transaction is only to read operational data), it is best to use Conf.MODE_READ.

      There are also some cases where starting a read-write transaction is not allowed, e.g. if we start a transaction towards the running data store is set to "writable-through-candidate" in confd.conf/ncs.conf, or if ConfD/NCS is running in HA secondary mode.

      Parameters:
      dbname - Database that the transaction should operate on.
      mode - Read or write mode.
      Throws:
      MaapiException - If the transaction could not be started see the Throwable.getMessage()
      IOException - Signals I/O exception on the underlying socket
      ConfException

    • startTrans

      public int startTrans(int dbname, int mode, String vendor, String product, String version, String clientId) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • startTrans2

      public int startTrans2(int dbname, int mode, int usid) throws IOException, ConfException
      Start a new transaction towards database within an existing user session specified by usid.

      If we want to start new transactions inside actions, we can use this function to execute the new transaction within the existing user session.

      See startTrans(int,int) for available options on dbname and mode mode.

      Parameters:
      dbname - Database that the transaction should operate on
      mode - Read or write mode
      usid - The user session id
      Throws:
      MaapiException - If the transaction could not be started see the Throwable.getMessage()
      IOException - Signals I/O exception on the underlying socket
      ConfException

    • startTransFlags

      public int startTransFlags(int dbname, int mode, int usid, EnumSet<MaapiFlag> flags) throws IOException, ConfException
      Start a new transaction towards the specified database dbname with a transaction mode mode with additional flags to control read/write sessions.

      This method makes it possible to provide flags that can otherwise be used with setFlags(int,EnumSet) already when starting a transaction, as well as setting the MaapiFlag.HIDE_INACTIVE and MaapiFlag.HIDE_ALL_HIDEGROUPS flag that can only be used with this function. Otherwise its has functionality equivalent to Maapi.startTrans2().

      Parameters:
      dbname - Database that the transaction should operate on. Possible values are STARTUP, RUNNING, CANDIDATE
      mode - Read or write mode. Possible values are READ and READ_WRITE
      usid - User session id
      flags - EnumSet of MaapiFlag values.
      Throws:
      IOException
      ConfException

    • startTransInTrans

      public int startTransInTrans(int mode, int usid, int tid) throws IOException, ConfException
      Start a new transaction within an existing user session and another transaction as backend
      Parameters:
      mode - Read or write mode. Possible values are READ and READ_WRITE
      usid - User session id
      tid - Backend transaction id
      Throws:
      MaapiException
      IOException
      ConfException

    • finishTrans

      public void finishTrans(int tid) throws IOException, ConfException
      Finish the transaction specified by transaction handle tid.

      If the transaction is implemented by an external database, this will invoke the finish callback.

      Parameters:
      tid - Transaction id of transaction to terminate.
      Throws:
      MaapiException
      IOException
      ConfException

    • attach

      public void attach(int tid, int nsi, int usid) throws IOException, ConfException
      Attach to a current transaction.

      While a transaction is executing, we have a number of situations where we wish to invoke user Java code which can interact in the transaction. One such situation is when we wish to write semantic validation code which is invoked in the validation phase of a transaction.

      This code needs to execute within the context of the executing transaction, it must thus have access to the "shadow" storage where all not-yet-committed data is kept.

      This method attaches to a existing transaction. See user guide chapter "Semantic Validation" for example code.

      Another situation where we wish to attach to the executing transaction is when we are using the notifications API and subscribe to notification of type NOTIF_COMMIT_DIFF and wish to read the committed diffs from the transaction.

      Parameters:
      tid - Transaction identifier
      nsi - Namespace identifier. Use 0 if we don't care which namespace is the default to choose if path elements are not properly prefixed.
      usid - Usid
      Throws:
      MaapiException
      IOException
      ConfException

    • attach

      public void attach(int tid, int nsi) throws IOException, ConfException
      Same as attach(int, int, int) with the exception that the User session id is implicit for the attached transaction.
      Parameters:
      tid - Transaction identifier
      nsi - Namespace identifier. Use 0 if we don't care which namespace is the default to choose if path elements are not properly prefixed.
      Throws:
      IOException
      ConfException

    • attach

      public void attach(int tid, String ns, int usid) throws IOException, ConfException
      Attach to a current transaction.

      While a transaction is executing, we have a number of situations where we wish to invoke user Java code which can interact in the transaction. One such situation is when we wish to write semantic validation code which is invoked in the validation phase of a transaction.

      This code needs to execute within the context of the executing transaction, it must thus have access to the "shadow" storage where all not-yet-committed data is kept.

      This method attaches to a existing transaction. See user guide chapter "Semantic Validation" for example code.

      Another situation where we wish to attach to the executing transaction is when we are using the notifications API and subscribe to notification of type NOTIF_COMMIT_DIFF and wish to read the committed diffs from the transaction.

      Parameters:
      tid - Transaction identifier
      ns - Namespace identifier
      usid - Usid
      Throws:
      MaapiException
      IOException
      ConfException

    • attach

      public void attach(int tid, String ns) throws IOException, ConfException
      Same as attach(int, String, int) with the exception that the User session id is implicit for the attached transaction.
      Parameters:
      tid - Transaction identifier
      ns - Namespace identifier
      Throws:
      IOException
      ConfException

    • attachInit

      public int attachInit() throws IOException, ConfException
      Attach to transaction available in phase0.

      This method is used to attach the Maapi socket to the special transaction available in phase0 used for CDB initialization and upgrade.

      Returns:
      the transaction handle for the init transaction
      Throws:
      IOException
      ConfException

    • detach

      public void detach(int tid) throws IOException, ConfException
      Detaches an attached MAAPI socket. This method is typically called in the finish phase in validation code. An attached MAAPI socket will be automatically detached when the transaction terminates. This method performs an explicit detach.
      Parameters:
      tid - Transaction Identifier
      Throws:
      MaapiException
      IOException
      ConfException

    • applyTrans

      public void applyTrans(int tid, boolean keepOpen) throws IOException, ConfException
      Apply a current transaction with transaction handle tid.

      Invoking the transaction methods in exactly the right order can be a bit complicated.

      The right order to invoke the methods is:

      Usually we do not require this fine grained control over the two-phase commit protocol. It is easier to use applyTrans which validates, prepares and eventually aborts or commits.

      A call to applyTrans must also eventually be followed by a call to finishTrans(int) which will terminate the transaction. For a readonly transaction, i.e. one started with Conf.MODE_READ, or for a read-write transaction where we haven't actually done any writes, we do not need to call any of the validate/prepare/commit/abort or apply methods, since there is nothing for them to do. Calling finishTrans to terminate the transaction is sufficient.

      The parameter keepopen can optionally be set to true, then the changes to the transaction are not discarded if validation fails. This feature is typically used by management applications that wish to present the validation errors to an operator and allow the operator to fix the validation errors and then later retry the apply sequence.

      Parameters:
      tid - Transaction id of transaction to commit
      keepOpen - If validation fails should the transaction be kept open or not
      Throws:
      ConfException - If the transaction is in badstate, for example if applyTrans is called twice.
      IOException

    • applyTrans

      public void applyTrans(int tid, boolean keepOpen, int flags) throws IOException, ConfException
      Apply a current transaction with transaction handle tid with additional flags (NCS Specific).

      Some NCS specific flags can be used:

      COMMIT_NCS_NO_REVISION_DROP means that NCS will not run its data model revision algorithm, thus requiring all participating managed devices to have all parts of the data models for all data contained in this transaction, i.e., this flag forces NCS to never silently drop any data set operations towards a device.

      COMMIT_NCS_NO_DEPLOY means that NCS will commit without running the FASTMAP algorithm, i.e, write the service instance data without activating the service(s). The service(s) can later be re-deployed to write the changes of the service(s) to the network.

      COMMIT_NCS_NO_NETWORKING means that the NCS device manager will not see these changes. Even if transaction manipulates data below /devices/device/config, nothing will be sent to the managed devices. Thus this is a way to manipulate CDB in NCS without generating any southbound traffic.

      COMMIT_NCS_NO_OUT_OF_SYNC_CHECK means that NCS will continue with the transaction even if NCS detects that a device's configuration is out of sync. The device's sync state is assumed to be unknown after such commit and the stored transaction id value is cleared.

      COMMIT_NCS_NO_OVERWRITE_WRITE_SET_ONLY means that NCS will check that the data that should be modified has not changed on the device compared to NCS's view of the data. This is fine-granular sync check; NCS verifies that NCS and the device is in sync regarding the data that will be modified. If they are not in sync, the transaction is aborted.

      COMMIT_NCS_NO_OVERWRITE_WRITE_AND_FULL_READ_SET means that NCS will check that the data that should be modified or any data read when computing the device modifications has not changed on the device compared to NCS's view of the data. This is fine-granular sync check; NCS verifies that NCS and the device is in sync regarding the data that will be modified. If they are not in sync, the transaction is aborted.

      COMMIT_NCS_NO_OVERWRITE_WRITE_AND_SERVICE_READ_SET means that NCS will check that the data that should be modified or any data read by services run in the transaction has not changed on the device compared to NCS's view of the data. This is fine-granular sync check; NCS verifies that NCS and the device is in sync regarding the data that will be modified. If they are not in sync, the transaction is aborted.

      COMMIT_NCS_USE_LSA means that NCS will force handling LSA nodes as such.

      COMMIT_NCS_NO_LSA means that NCS will not handle any of the LSA nodes as such. These nodes will be handled as any other device.

      COMMIT_NCS_RECONCILE_KEEP_NON_SERVICE_CONFIG means that all data which existed before the service was created will now be owned by the service. When the service is removed that data will also be removed. In technical terms the reference count will be decreased by one for everything which existed. Note that this flag has no effect on initial service creation. Any manually configured data that exists below in the configuration tree will be kept.

      COMMIT_NCS_RECONCILE_DISCARD_NON_SERVICE_CONFIG means that all data which existed before the service was created will now be owned by the service. When the service is removed that data will also be removed. In technical terms the reference count will be decreased by one for everything which existed. Note that this flag has no effect on initial service creation. Any manually configured data that exists below in the configuration tree will be discarded.

      The flags are bits and can be ORed together.

      Parameters:
      tid - Transaction id of transaction to commit
      keepOpen - If validation fails should the transaction be kept open or not
      flags - Bitwise ORed flags
      Throws:
      MaapiException
      IOException
      ConfException

    • applyTransParams

      public ApplyResult applyTransParams(int tid, boolean keepOpen, CommitParams params) throws IOException, ConfException
      Apply a current transaction with transaction handle tid with additional NCS specific parameters.
      Parameters:
      tid - Transaction id of transaction to commit
      keepOpen - If validation fails should the transaction be kept open or not
      params - Commit parameters, see CommitParams
      Returns:
      An instance of DryRunResult if dry-run was requested. An instance of CommitQueueResult if commit through commit queue was requested. Otherwise an instance of ApplyResult.
      Throws:
      IOException
      ConfException

    • ncsRunWithRetry

      public boolean ncsRunWithRetry(MaapiRetryableOp op) throws IOException, ConfException
      Run op with a new read-write transaction against the RUNNING datastore. In case of a conflict, retry running op.

      Equivalent of ncsRunWithRetry(op, 10, new CommitParams()).

      See ncsRunWithRetry

      Throws:
      IOException
      ConfException

    • ncsRunWithRetry

      public boolean ncsRunWithRetry(MaapiRetryableOp op, int maxNumRetries, CommitParams commitParams) throws IOException, ConfException
      Run op with a new read-write transaction against the RUNNING datastore. In case of a conflict, retry running op.

      Equivalent of ncsRunWithRetry(op, maxNumRetries, commitParams, EnumSet.noneOf(MaapiFlag.class)).

      See ncsRunWithRetry(MaapiRetryableOp, int, CommitParams, int, EnumSet)

      Throws:
      IOException
      ConfException

    • ncsRunWithRetry

      public boolean ncsRunWithRetry(MaapiRetryableOp op, int maxNumRetries, CommitParams commitParams, int usid, EnumSet<MaapiFlag> flags) throws IOException, ConfException
      Run op with a new read-write transaction against the RUNNING datastore. In case of a conflict, retry running op.

      Run op with a new read-write transaction, applying it if op returns true. The op is only retried in case of transaction conflicts. Each retry is run using a new transaction.

      The last conflict exception is thrown in case the maximum number of retries is reached.

      Parameters:
      op - Object implementing the com.tailf.maapi.MaapiRetryableOp interface
      maxNumRetries - Maximum number of retries running op in case of a conflict
      commitParams - Commit parameters, see CommitParams
      usid - User session id
      flags - Enumset of MaapiFlag
      Returns:
      false if the maximum number of retries is reached
      Throws:
      IOException
      ConfException

    • getTransParams

      public CommitParams getTransParams(int tid) throws IOException, ConfException
      Get commit parameters for a transaction.
      Parameters:
      tid - Transaction id of transaction to get commit parameters for
      Returns:
      the commit parameters
      Throws:
      IOException
      ConfException

    • getRollbackId

      public int getRollbackId(int tid) throws IOException, ConfException
      Get rollback id for committed transaction specified by transaction handle tid.

      This methods returns the fixed rollback id of the rollback file created during commit of the transaction. If rollbacks are disabled or no rollback was created this returns -1.

      Parameters:
      tid - Transaction Identifier
      Throws:
      MaapiException
      IOException
      ConfException

    • validateTrans

      public void validateTrans(int tid, boolean unlock, boolean force) throws IOException, ConfException
      Validates a transaction specified by transaction handle tid

      This method validates all data written in the transaction. This includes all XML checks, checking for uniqueness and dangling pointers. It also includes all defined semantic validation, i.e. user programs that have registered functions under validation points. (See user manual chapter Semantic Validation).

      If this method throws an exception due to a validation error, the transaction is still open for further editing. If unlock is true, the transaction is open for further editing even if validation succeeds. If unlock is false and the method returns, the next method to be called MUST be prepareTrans(int) or finishTrans(int).

      unlock = true can be used to implement a 'validate' command which can be given in the middle of an editing session. The first thing that happens is that a lock is set. If unlock = true, the lock is released on success. The lock is always released on failure. The force parameter should normally be false. It has no effect for a transaction towards the running or startup data stores, validation is always performed. For a transaction towards the candidate data store, validation will not be done unless force true. Avoiding this validation is preferable if we are going to commit the candidate to running e.g with candidateCommit(), since otherwise the validation will be done twice. However if we are implementing a 'validate' command, we should set force = true

      Parameters:
      tid - Transaction Identifier
      unlock - if true the transaction is open for further editing
      force - if true validation will performed also for candidate data store
      Throws:
      MaapiException
      IOException
      ConfException

    • prepareTrans

      public void prepareTrans(int tid) throws IOException, ConfException
      Prepares the transaction specified by transaction handle tid. This method must be called as first part of two-phase commit. After this method has been called commitTrans or abortTrans must be called.

      It will invoke the prepare callback in all participants in the transaction. If all participants reply with OK, the second phase of the two-phase commit procedure is commenced.

      Parameters:
      tid - Transaction Identifier
      Throws:
      MaapiException
      IOException
      ConfException

    • prepareTrans

      public void prepareTrans(int tid, int flags) throws IOException, ConfException
      Prepares the transaction specified by transaction handle tid. This method must be called as first part of two-phase commit. After this method has been called commitTrans or abortTrans must be called.

      It will invoke the prepare callback in all participants in the transaction. If all participants reply with OK, the second phase of the two-phase commit procedure is commenced.

      For a definition of the flags, see applyTrans(int,boolean)

      Parameters:
      tid - Transaction Identifier
      flags - Bitwise ORed flags
      Throws:
      MaapiException
      IOException
      ConfException

    • commitTrans

      public void commitTrans(int tid) throws IOException, ConfException
      Commit a transaction specified by transaction handle tid. Final step of a two-phase commit. validateTrans(int,boolean,boolean) and prepareTrans must be called prior to commitTrans
      Parameters:
      tid - Transaction Identifier
      Throws:
      MaapiException
      IOException
      ConfException

    • abortTrans

      public void abortTrans(int tid) throws IOException, ConfException
      Abort a transaction specified by transaction handle tid. Called if a two-phase commit should be aborted after having performed validateTrans or prepareTrans.
      Parameters:
      tid - Transaction Identifier
      Throws:
      MaapiException
      IOException
      ConfException

    • diffIterate

      public void diffIterate(int tid, MaapiDiffIterate iter) throws IOException, ConfException
      Iterates through the transaction diff.

      For all diffs in the transaction the supplied MaapiDiffIterate.iterate(ConfObject[],DiffIterateOperFlag, ConfObject,ConfObject,Object) (callback) method will be called.

      This method can be called from an attached MAAPI session. The purpose of the function is to iterate through the transaction diff. It can typically be used in conjunction with the notification API when we subscribe to NOTIF_COMMIT_DIFF events.

      For all diffs in the transaction the supplied callback function iterate will be called. The iterate callback receives the keypath which uniquely identifies which element in the XML tree that is affected, the operation, and an optional value.

      iterate is called for each modified list entry, and for each modified leaf node. If the node is a list entry, op is one of MOP_CREATED, MOP_DELETED or MOP_MODIFIED If the node is a leaf node, op is one of MOP_DELETED or MOP_VALUE_SET.

      If iterate returns ITER_STOP, no more iteration is done. If iterate returns ITER_RECURSE iteration continues with all children to the node. If iterate returns ITER_CONTINUE iteration ignores the children to the node (if any), and continues with the node's sibling.

      The different commit messages are not subjected to AAA checks, i.e. regardless of which path we have and which context was used to create the MAAPI socket, all changed values are sent on the socket.

      Parameters:
      tid - Transaction handle
      iter - A MaapiDiffIterate object
      Throws:
      MaapiException - Failed diffIterate
      IOException - Failed to read/write maapi socket
      ConfException

    • diffIterate

      public void diffIterate(int tid, MaapiDiffIterate iter, String fmt, Object... args) throws IOException, ConfException
      Iterates through the transaction diff.

      For all diffs in the transaction the supplied MaapiDiffIterate.iterate(ConfObject[],DiffIterateOperFlag, ConfObject,ConfObject,Object) (callback) method will be called.

      This method can be called from an attached MAAPI session. The purpose of the function is to iterate through the transaction diff. It can typically be used in conjunction with the notification API when we subscribe to NOTIF_COMMIT_DIFF events.

      For all diffs in the transaction the supplied callback function iterate will be called. The iterate callback receives the keypath which uniquely identifies which element in the XML tree that is affected, the operation, and an optional value.

      iterate is called for each modified list entry, and for each modified leaf node. If the node is a list entry, op is one of MOP_CREATED, MOP_DELETED or MOP_MODIFIED If the node is a leaf node, op is one of MOP_DELETED or MOP_VALUE_SET.

      If iterate returns ITER_STOP, no more iteration is done. If iterate returns ITER_RECURSE iteration continues with all children to the node. If iterate returns ITER_CONTINUE iteration ignores the children to the node (if any), and continues with the node's sibling.

      The different commit messages are not subjected to AAA checks, i.e. regardless of which path we have and which context was used to create the MAAPI socket, all changed values are sent on the socket.

      Parameters:
      tid - Transaction handle
      iter - A MaapiDiffIterate object
      Throws:
      MaapiException - Failed diffIterate
      IOException - Failed to read/write maapi socket
      ConfException

    • diffIterate

      public void diffIterate(int tid, MaapiDiffIterate iter, Object initstate, String fmt, Object... args) throws IOException, ConfException
      Iterates through the transaction diff.

      For all diffs in the transaction the supplied MaapiDiffIterate.iterate(ConfObject[],DiffIterateOperFlag, ConfObject,ConfObject,Object) (callback) method will be called.

      This method can be called from an attached MAAPI session. The purpose of the function is to iterate through the transaction diff. It can typically be used in conjunction with the notification API when we subscribe to NOTIF_COMMIT_DIFF events.

      For all diffs in the transaction the supplied callback function iterate will be called. The iterate callback receives the keypath which uniquely identifies which element in the XML tree that is affected, the operation, and an optional value.

      iterate is called for each modified list entry, and for each modified leaf node. If the node is a list entry, op is one of MOP_CREATED, MOP_DELETED or MOP_MODIFIED If the node is a leaf node, op is one of MOP_DELETED or MOP_VALUE_SET.

      If iterate returns ITER_STOP, no more iteration is done. If iterate returns ITER_RECURSE iteration continues with all children to the node. If iterate returns ITER_CONTINUE iteration ignores the children to the node (if any), and continues with the node's sibling.

      The different commit messages are not subjected to AAA checks, i.e. regardless of which path we have and which context was used to create the MAAPI socket, all changed values are sent on the socket.

      Parameters:
      tid - Transaction handle
      iter - A MaapiDiffIterate object
      Throws:
      MaapiException - Failed diffIterate
      IOException - Failed to read/write maapi socket
      ConfException

    • diffIterate

      public void diffIterate(int tid, Object initstate, EnumSet<DiffIterateFlags> flags, MaapiDiffIterate iter, ConfPath path) throws IOException, ConfException
      Iterates through the transaction diff.

      For all diffs in the transaction the supplied MaapiDiffIterate.iterate(ConfObject[],DiffIterateOperFlag, ConfObject,ConfObject,Object) (callback) method will be called.

      This method can be called from an attached MAAPI session. The purpose of the function is to iterate through the transaction diff. It can typically be used in conjunction with the notification API when we subscribe to NOTIF_COMMIT_DIFF events.

      For all diffs in the transaction the supplied callback function iterate will be called. The iterate callback receives the keypath which uniquely identifies which element in the XML tree that is affected, the operation, and an optional value.

      iterate is called for each modified list entry, and for each modified leaf node. If the node is a list entry, op is one of MOP_CREATED, MOP_DELETED or MOP_MODIFIED If the node is a leaf node, op is one of MOP_DELETED or MOP_VALUE_SET. If the flags argument is set to DiffIterateFlags.ITER_WANT_ATTR also attribute changes will be iterated over with op MOP_ATTR_SET and new and old values as ConfAttributeValue

      If iterate returns ITER_STOP, no more iteration is done. If iterate returns ITER_RECURSE iteration continues with all children to the node. If iterate returns ITER_CONTINUE iteration ignores the children to the node (if any), and continues with the node's sibling.

      The different commit messages are not subjected to AAA checks, i.e. regardless of which path we have and which context was used to create the MAAPI socket, all changed values are sent on the socket.

      Parameters:
      tid - Transaction handle
      initstate - arbitrary object passed to the iterator
      flags - set of DiffIterateFlags flags that controls the iteration, for Maapi only DiffIterateFlags.ITER_WANT_ATTR is supported
      iter - A MaapiDiffIterate object
      path - ConfPath
      Throws:
      MaapiException - Failed diffIterate
      IOException - Failed to read/write maapi socket
      ConfException

    • iterate

      public void iterate(int tid, Object initstate, EnumSet<ConfIterateFlags> flags, MaapiIterate iter, ConfPath path) throws IOException, ConfException
      Iterates through all the data in a transaction.

      For all data elements in the transaction the supplied MaapiIterate.iterate(ConfObject[],ConfObject, ConfAttributeValue[],Object) (callback) method will be called.

      This method can be called from an attached MAAPI session.

      The iterate callback receives the keypath which uniquely identifies which element in the XML tree that is affected, the operation, and an optional value.

      iterate is called for each list entry, and for each leaf node. If the node is a list entry, op is one of MOP_CREATED, MOP_DELETED or MOP_MODIFIED If the node is a leaf node, op is one of MOP_DELETED or MOP_VALUE_SET. If the flags argument is set to ConfIterateFlags.ITER_WANT_ATTR also attribute changes will be iterated over with op MOP_ATTR_SET and new and old values as ConfAttributeValue

      If iterate returns ITER_STOP, no more iteration is done. If iterate returns ITER_RECURSE iteration continues with all children to the node. If iterate returns ITER_CONTINUE iteration ignores the children to the node (if any), and continues with the node's sibling.

      The different commit messages are not subjected to AAA checks, i.e. regardless of which path we have and which context was used to create the MAAPI socket, all changed values are sent on the socket.

      Parameters:
      tid - Transaction handle
      initstate - arbitrary object passed to the iterator
      flags - set of ConfIterateFlags flags that controls the iteration, for Maapi only ConfIterateFlags.ITER_WANT_ATTR is supported
      iter - A MaapiIterate object
      path - ConfPath
      Throws:
      IOException
      ConfException

    • setLabel

      public void setLabel(int tid, String label) throws IOException, ConfException
      Set the "Label" that is stored in the rollback file when a transaction towards running is committed. Setting the "Label" for transactions via candidate can be done when the candidate is committed to running, by using the candidateCommitInfo(java.lang.String, java.lang.String) method. For a confirmed commit, the "Label" must also be given via the candidateConfirmedCommitInfo(int, java.lang.String, java.lang.String) method.
      Parameters:
      tid - Transaction Identifier
      label - Label
      Throws:
      MaapiException
      IOException
      ConfException

    • setComment

      public void setComment(int tid, String comment) throws IOException, ConfException
      Set the "Comment" that is stored in the rollback file when a transaction towards running is committed. Setting the "Comment" for transactions via candidate can be done when the candidate is committed to running, by using the candidateCommitInfo(java.lang.String, java.lang.String) method. For a confirmed commit, the "Comment" must also be given via the candidateConfirmedCommitInfo(int, java.lang.String, java.lang.String) method.
      Parameters:
      tid - Transaction Identifier
      comment - Comment
      Throws:
      MaapiException
      IOException
      ConfException

    • setNamespace

      public void setNamespace(int tid, String ns) throws IOException, ConfException
      Before can invoke any of read or write functions, we must indicate which namespace we are going to use. It is possible to change the namespace several times during a transaction.

      The ns string is the namespace URL

      Parameters:
      tid - Transaction Identifier
      ns - Namespace uri
      Throws:
      MaapiException
      IOException
      ConfException

    • setNamespace

      public void setNamespace(int tid, int nsid) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • cd

      public void cd(int tid, String fmt, Object... arguments) throws ConfException, IOException
      This function mimics the behavior of the UNIX "cd" command. It changes our working position in the XML tree. If we are worried about performance, it is more efficient to invoke cd() to some position in the XML tree and there perform a series of operations using relative paths than it is to perform the equivalent series of operations using absolute paths.

      The cd() function is also very useful when writing generic code for accessing parts of the configuration tree.

      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      MaapiException
      IOException
      ConfException

    • pushd

      public void pushd(int tid, String fmt, Object... arguments) throws ConfException, IOException
      Behaves like cd() with the exception that we can subsequently call popd() and return to the previous position in the XML data tree.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      MaapiException
      IOException
      ConfException

    • popd

      public void popd(int tid) throws ConfException, IOException
      Pops the top position of the directory stack and changes directory
      Parameters:
      tid - Transaction Identifier
      Throws:
      MaapiException
      IOException
      ConfException

    • exists

      public boolean exists(int tid, ConfPath path) throws IOException, ConfException
      Boolean function which return 1 or 0 if a path defines an existing element in the XML data tree.
      Parameters:
      tid - Transaction Identifier
      path - ConfPath instance
      Throws:
      MaapiException
      IOException
      ConfException

    • exists

      public boolean exists(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • getNumberOfInstances

      public int getNumberOfInstances(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Return the number of instances in a list. The path must lead to a list in the the model.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      MaapiException
      IOException
      ConfException

    • getNumberOfInstances

      public int getNumberOfInstances(int tid, ConfPath path) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • getElem

      public ConfValue getElem(int tid, String fmt, Object... arguments) throws IOException, ConfException
      This reads a value from the path in fmt and returns the result. The path must lead to a leaf element in the XML data tree.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      MaapiException
      IOException
      ConfException

    • getElem

      public ConfValue getElem(int tid, ConfPath path) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • safeGetElem

      public ConfValue safeGetElem(int tid, ConfPath path) throws IOException, ConfException

      Reads a value from the path specified

      The path must lead to a leaf element in the data tree.

      This is a equivalent method ofgetElem(int,String,Object[]) method which returns null if the element doesn't exist instead of throwing a exception.

      Parameters:
      tid - transaction handle
      path - leaf element in data tree
      Throws:
      ConfException
      IOException

    • safeGetElem

      public ConfValue safeGetElem(int tid, String fmt, Object... arguments) throws IOException, ConfException
      This reads a value from the path in fmt and returns the result. The path must lead to a leaf element in the XML data tree. This is a variant of the getElem() method which returns null if the element doesn't exist
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      MaapiException
      IOException
      ConfException

    • getObject

      public ConfObject[] getObject(int tid, String fmt, Object... arguments) throws IOException, ConfException
      This reads a container object or a list entry object from the path in fmt and returns the result. The path must lead to a a list entry or a container element in the XML data tree. The return value is an array of ConfObjects that describe the entire structure. All plain values in the structure, such as strings, ints ip addresses are represented as ConfValue instances. If the structure contains containers, they are represented as ConfTag instances. Finally, optional leafs and containers in the structure that are missing are represented as ConfTypeDescriptor instances with type set to ConfObject.J_NOEXISTS.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Returns:
      An array of ConfObject which describes the object.
      Throws:
      MaapiException
      IOException
      ConfException

    • safeGetObject

      public ConfObject[] safeGetObject(int tid, String fmt, Object... arguments) throws IOException, ConfException
      This is a variant of getObject() that returns null if the object doesn't exist
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Returns:
      An array of ConfObject which describes the object.
      Throws:
      MaapiException
      IOException
      ConfException

    • setObject

      public void setObject(int tid, ConfObject[] values, String fmt, Object... arguments) throws IOException, ConfException
      This writes a container object or a list entry object from the path in fmt and returns the result. The path must lead to a a list entry or a container element in the XML data tree. The values to set is an array of ConfObjects that describe the entire structure. All plain values in the structure, such as strings, ints ip addresses are represented as ConfValue instances. If the structure contains containers, they are represented as ConfTag instances. Finally, optional leafs and containers in the structure that are missing are represented as ConfTypeDescriptor instances with type set to ConfObject.J_NOEXISTS.
      Parameters:
      tid - Transaction Identifier
      values -
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      MaapiException
      IOException
      ConfException

    • setValues

      public void setValues(int tid, List<ConfXMLParam> params, ConfPath path) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation. If the container element itself, or any sub-elements that are specified as existing, do not exist before this call, they will be created, otherwise the existing values will be updated. Both non-optional and optional elements may be omitted from the array, and all omitted elements are left unchanged.
      Parameters:
      tid -
      params -
      path -
      Throws:
      IOException
      ConfException

    • setValues

      public void setValues(int tid, List<ConfXMLParam> params, String fmt, Object... arguments) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation. If the container element itself, or any sub-elements that are specified as existing, do not exist before this call, they will be created, otherwise the existing values will be updated. Both non-optional and optional elements may be omitted from the array, and all omitted elements are left unchanged.
      Parameters:
      params -
      fmt -
      arguments -
      Throws:
      IOException
      ConfException

    • setValues

      public void setValues(int tid, ConfXMLParam[] params, String fmt, Object... arguments) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation. If the container element itself, or any sub-elements that are specified as existing, do not exist before this call, they will be created, otherwise the existing values will be updated. Both non-optional and optional elements may be omitted from the array, and all omitted elements are left unchanged.
      Parameters:
      tid -
      params -
      fmt -
      arguments -
      Throws:
      IOException
      ConfException

    • setValues

      public void setValues(int tid, ConfXMLParam[] params, ConfPath path) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation. If the container element itself, or any sub-elements that are specified as existing, do not exist before this call, they will be created, otherwise the existing values will be updated. Both non-optional and optional elements may be omitted from the array, and all omitted elements are left unchanged.
      Parameters:
      tid -
      params -
      path -
      Throws:
      IOException
      ConfException

    • sharedSetValues

      public void sharedSetValues(int tid, List<ConfXMLParam> params, ConfPath path) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation from NCS FastMap code. This method is the equivalent of setValues() except that it can only be called from NCS FastMap service code. It will ensure that when service code manipulates elements, everything will always be cleaned up when the service is removed.
      Parameters:
      tid -
      params -
      path -
      Throws:
      IOException
      ConfException

    • sharedSetValues

      public void sharedSetValues(int tid, List<ConfXMLParam> params, String fmt, Object... arguments) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation from NCS FastMap code.
      Parameters:
      tid -
      params -
      fmt -
      arguments -
      Throws:
      IOException
      ConfException

    • sharedSetValues

      public void sharedSetValues(int tid, ConfXMLParam[] params, String fmt, Object... arguments) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation from NCS FastMap code.
      Parameters:
      tid -
      params -
      fmt -
      arguments -
      Throws:
      IOException
      ConfException

    • sharedSetValues

      public void sharedSetValues(int tid, ConfXMLParam[] params, ConfPath path) throws IOException, ConfException
      Set arbitrary sub-elements of a container element in one bulk operation from NCS FastMap code. Everything that is set or created with this method, also get's an additional attribute set, called 'Backpointer' which points back to the service instance that created the entity in the first place. This makes it possible to look at the /devices tree and answer the question which parts of the device configurtaion was created by which service(es).
      Parameters:
      tid -
      params -
      path -
      Throws:
      IOException
      ConfException

    • getValues

      public <T extends List<ConfXMLParam>> T getValues(int tid, T params, String fmt, Object... arguments) throws IOException, ConfException
      Read an arbitrary set of sub-elements of a container element.

      The params list must be pre-populated based on the specification of the ConfXMLParam array structure format. Where ConfXMLParamValue value element set by ConfXMLParamValue.setValue(ConfObject) method is given as follow:

      • ConfNoExists means that the value should be read from the transaction and stored in the array.
      • ConfXMLParamStart, ConfXMLParamStop are used as per the specification.
      • Keys to select list entries can be given with their values.

      All elements have the same position in the array after the call, In order to simplify extraction of the values - this means that optional elements that were requested but didn't exist will have ConfNoExists (as a the ConfXMLParam.getValue() return value in the corresponding position in a ConfXMLParamValue) rather than being omitted from the array. However requesting a list entry that doesn't exist will throw a exception indicating that the instance does not exits.

      Type Parameters:
      T - the type list holding the structure
      Parameters:
      tid - transaction handle
      arguments - optional parameter for substitution in fmt
      params - pre-populated structure of the elements to be extracted
      Throws:
      MaapiException - If the the call failed for some reason see the Throwable.getMessage() for details.
      IOException - Signals I/O exception of some kind
      ConfException
      See Also:

    • getValues

      public <T extends List<ConfXMLParam>> T getValues(int tid, T params, ConfPath path) throws IOException, ConfException
      Read an arbitrary set of sub-elements of a container element.

      The params list must be pre-populated based on the specification of the ConfXMLParam array structure format. Where ConfXMLParamValue value element set by ConfXMLParamValue.setValue(ConfObject) method is given as follow:

      • ConfNoExists means that the value should be read from the transaction and stored in the array.
      • ConfXMLParamStart, ConfXMLParamStop are used as per the specification.
      • Keys to select list entries can be given with their values.

      All elements have the same position in the array after the call, In order to simplify extraction of the values - this means that optional elements that were requested but didn't exist will have ConfNoExists (as a the ConfXMLParam.getValue() return value in the corresponding position in a ConfXMLParamValue) rather than being omitted from the array. However requesting a list entry that doesn't exist will throw a exception indicating that the instance does not exits.

      Type Parameters:
      T - the type list holding the structure
      Parameters:
      tid - transaction handle
      path - the path pointing to the location of extraction
      params - pre-populated structure of the elements to be extracted
      Throws:
      MaapiException - If the the call failed for some reason see the Throwable.getMessage() for details.
      IOException - Signals I/O exception of some kind
      ConfException
      See Also:

    • getValues

      public <T extends ConfXMLParam> T[] getValues(int tid, T[] params, String fmt, Object... arguments) throws IOException, ConfException
      Read an arbitrary set of sub-elements of a container element.

      The params array must be pre-populated based on the specification of the ConfXMLParam array structure format. Where ConfXMLParamValue value element set by ConfXMLParamValue.setValue(ConfObject) method is given as follow:

      • ConfNoExists means that the value should be read from the transaction and stored in the array.
      • ConfXMLParamStart, ConfXMLParamStop are used as per the specification.
      • Keys to select list entries can be given with their values.

      All elements have the same position in the array after the call, In order to simplify extraction of the values - this means that optional elements that were requested but didn't exist will have ConfNoExists (as a the ConfXMLParam.getValue() return value in the corresponding position in a ConfXMLParamValue) rather than being omitted from the array. However requesting a list entry that doesn't exist will throw a exception indicating that the instance does not exits.

      Type Parameters:
      T - type of the elements contained in the structure
      Parameters:
      tid - transaction handle
      params - pre-populated structure of the elements to be extracted
      fmt - path string
      arguments - optional parameter for substitution in fmt
      Throws:
      MaapiException - If the the call failed for some reason see the Throwable.getMessage() for details.
      IOException - Signals I/O exception of some kind
      ConfException
      See Also:

    • getValues

      public <T extends ConfXMLParam> T[] getValues(int tid, T[] params, ConfPath path) throws IOException, ConfException
      Read an arbitrary set of sub-elements of a container element.

      The params array must be pre-populated based on the specification of the ConfXMLParam array structure format. Where ConfXMLParamValue value element set by ConfXMLParamValue.setValue(ConfObject) method is given as follow:

      • ConfNoExists means that the value should be read from the transaction and stored in the array.
      • ConfXMLParamStart, ConfXMLParamStop are used as per the specification.
      • Keys to select list entries can be given with their values.

      All elements have the same position in the array after the call, In order to simplify extraction of the values - this means that optional elements that were requested but didn't exist will have ConfNoExists (as a the ConfXMLParam.getValue() return value in the corresponding position in a ConfXMLParamValue) rather than being omitted from the array. However requesting a list entry that doesn't exist will throw a exception indicating that the instance does not exits.

      Type Parameters:
      T - type of the elements contained in the structure
      Parameters:
      tid - transaction handle
      params - pre-populated structure of the elements to be extracted
      path - the path pointing to the location of extraction
      Throws:
      MaapiException - If the the call failed for some reason see the Throwable.getMessage() for details.
      IOException - Signals I/O exception of some kind
      ConfException
      See Also:

    • newCursor

      public MaapiCursor newCursor(int tid, String fmt, Object... arguments) throws IOException, ConfException

      Creates a cursor for a list specified by fmt.

      The MaapiCursor is used to iterate over the keys of a list.

      When we wish to iterate over key entries we must first create a cursor.

      The cursor instance is subsequently used in getNext(MaapiCursor) to retrieve the next key instance in the list. When the cursor retrieves null the whole list has been iterated.

      An exhausted cursor cannot be reset.

      For example, if we have the following YANG model:

      
 module mtest {
   namespace "http://tail-f.com/test/mtest/1.0";
   prefix mtest;

   import ietf-inet-types {
     prefix inet;
   }

   container servers {
     list server {
       key name;
       max-elements 64;
       leaf name {
         type string;
       }
       leaf ip {
         type inet:ip-address;
         mandatory true;
       }
       leaf port {
         type inet:port-number;
         mandatory true;
       }
     }
   }
 }

      Example usage: 

      
 MaapiCursor c = maapi.newCursor(tid, "/mtest:mtest/servers/server");
 ConfKey x;

 while ((x = maapi.getNext(c)) != null) {
    ConfValue nameValue =
        maapi.getElem(tid, "/mtest:mtest/servers/server{%x}/name", x);
    ConfValue ipValue =
        maapi.getElem(tid, "/mtest:mtest/servers/server{%x}/ip", x);
    ConfValue portValue =
        maapi.getElem(tid, "/mtest:mtest/servers/server{%x}/port",x);
 }
      Parameters:
      tid - current transaction id
      fmt - path of the list to be iterated
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException

    • newCursor

      public MaapiCursor newCursor(int tid, ConfPath path) throws IOException, ConfException

      Creates a cursor for a list specified by path

      The MaapiCursor is used to iterate over the keys of a list.

      When we wish to iterate over key entries we must first create a cursor.

      The cursor instance is subsequently used in getNext(MaapiCursor) to retrieve the next key instance in the list. When the cursor retrieves null the whole list has been iterated and the cursor can not be reset.

      Parameters:
      tid - current transaction id
      path - path of the list to be iterated
      Throws:
      IOException
      ConfException

    • newCursorWithFilter

      public MaapiCursor newCursorWithFilter(int tid, String filter, String fmt, Object... arguments) throws IOException, ConfException

      Creates a cursor for a list specified by fmt with an XPath filter specified by filter.

      The MaapiCursor is used to iterate over the keys a list.

      When we wish to iterate over key entries we must first create a cursor.

      The cursor instance is subsequently used in getNext(MaapiCursor) to retrieve the next key instance in the list. When the cursor retrieves null the whole list has been iterated and the cursor can not be reset.

      If filter is not null, only keys of elements matching the filter will be included in the iteration. If filter is null, this method behaves just as newCursor(int, String, Object...)

      Given the same example model as in newCursor(int, String, Object...) one could iterate over servers on the 10.x.x.x network with port numbers above 8000 using the following cursor call: 

      
 MaapiCursor c =
     maapi.newCursorWithFilter(tid,
                               "starts-with(ip, \"10.\") and port > 8000",
                               "/mtest:mtest/servers/server");
      Parameters:
      tid - current transaction id
      filter - XPath filter for filtering the list
      fmt - path of the list to be iterated
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException

    • newCursorWithFilter

      public MaapiCursor newCursorWithFilter(int tid, String filter, ConfPath path) throws IOException, ConfException

      Creates a cursor for a list specified by path with an XPath filter specified by filter.

      The MaapiCursor is used to iterate over the keys of a list.

      When we wish to iterate over key entries we must first create a cursor.

      The cursor instance is subsequently used in getNext(MaapiCursor) to retrieve the next key instance in the list. When the cursor retrieves null the whole list has been iterated and the cursor can not be reset.

      If filter is not null, only keys of elements matching the filter will be included in the iteration. If filter is null, this method behaves just as newCursor(int, ConfPath)

      Parameters:
      tid - current transaction id
      filter - XPath filter for filtering the list
      path - path of the list to be iterated
      Throws:
      IOException
      ConfException

    • getNext

      public ConfKey getNext(MaapiCursor c) throws IOException, ConfException
      Iterates and gets the keys for the next element pinpointed by the MaapiCursor initially retrieved by newCursor(int, String, Object...). With the key(s) it is possible to navigate further down the model.

      For example, to read the port element from the 'server' example model, we would do: 

      
 MaapiCursor c = maapi.newCursor(tid,
                                 "/mtest:mtest/servers/server");
 ConfKey x = maapi.getNext(c);
 while (x != null) {
     ConfObject p;
     p = maapi.getElem(tid,
                       "/mtest:mtest/servers/server{%x}/port", x);
     // ....
     x = maapi.getNext(c);
 }
      Parameters:
      c - MaapiCursor
      Returns:
      ConfKey for the retrieved element
      Throws:
      IOException
      ConfException

    • findNext

      public ConfKey findNext(MaapiCursor c, ConfFindNextType type, ConfKey key) throws IOException, ConfException
      The findNext method makes it possible to jump forward to an element in the model at a position defined by the MaapiCursor After the findNext call the same MaapiCursor can be used in subsequent getNext calls.
      Parameters:
      c - MaapiCursor for path
      type - ConfFindNextType if same element as key or element after key should be retrieved
      key - ConfKey for the searched element
      Returns:
      ConfKey for the retrieved element or null if not found
      Throws:
      IOException
      ConfException

    • getObjects

      public List<ConfObject[]> getObjects(MaapiCursor c, int numOfObjects, int numOfInstances) throws IOException, ConfException
      Get several list instances with one request. A prerequisite is that a MaapiCursor must have been initialized for the list and supplied as an argument to this call. For each list instance the argument numOfObjects controls the maximum number of elements that will be retrieved. The objects are added in schema order. The numOfInstances argument controls the maximum number of list instances that should be retrived. If the list is empty or the cursor have already iterated through all list instances then the returned list will be empty.
      Parameters:
      c - MaapiCursor on current list
      numOfObjects - Number of object retrieved from a list instance
      numOfInstances - Number of list instances retrieved in this call
      Returns:
      List<ConfObject[]> containing list instances.
      Throws:
      IOException
      ConfException

    • setElem

      public void setElem(int tid, ConfObject value, String fmt, Object... arguments) throws IOException, ConfException
      Set value to a leaf node.

      There two different methods to set a value to a leaf node. One where the value is a string and one where the value to set is a ConfObject. The string version is useful when we have implemented a management agent where the user enters values as strings.

      The version with ConfObject is useful when we are setting values which we have just read from various API methods that returns ConfObject.

      Parameters:
      tid - Transaction Identifier
      value -
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException

    • setElem

      public void setElem(int tid, ConfObject value, ConfPath path) throws IOException, ConfException
      Set value to a leaf node.

      There two different methods to set a value to a leaf node. One where the value is a string and one where the value to set is a ConfObject. The string version is useful when we have implemented a management agent where the user enters values as strings.

      The version with ConfObject is useful when we are setting values which we have just read from various API methods that returns ConfObject.

      Parameters:
      tid - Transaction Identifier
      value -
      path -
      Throws:
      IOException
      ConfException

    • setElem

      public void setElem(int tid, String value, String fmt, Object... arguments) throws IOException, ConfException
      Set value to a leaf node.

      There two different methods to set a value to a leaf node. One where the value is a string and one where the value to set is a ConfObject. The string version is useful when we have implemented a management agent where the user enters values as strings.

      The version with ConfObject is useful when we are setting values which we have just read from various API methods that returns ConfObject.

      Parameters:
      tid - Transaction Identifier
      value -
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException

    • setElem

      public void setElem(int tid, String value, ConfPath path) throws IOException, ConfException
      Set value to a leaf node.

      There two different methods to set a value to a leaf node. One where the value is a string and one where the value to set is a ConfObject. The string version is useful when we have implemented a management agent where the user enters values as strings.

      The version with ConfObject is useful when we are setting values which we have just read from various API methods that returns ConfObject.

      Parameters:
      tid - Transaction Identifier
      value -
      path - ConfPath instance
      Throws:
      IOException
      ConfException

    • sharedSetElem

      public void sharedSetElem(int tid, ConfObject value, String fmt, Object... arguments) throws IOException, ConfException
      Set value to a leaf node from NCS FastMap code This method is the equivalent of setElem() except that it can only be called from NCS FastMap service code. It will ensure that when service code manipulates leaves, everything will always be cleaned up when the service is removed.
      Parameters:
      tid - Transaction Identifier
      value -
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException

    • sharedSetElem

      public void sharedSetElem(int tid, ConfObject value, ConfPath path) throws IOException, ConfException
      Set value to a leaf node from NCS FastMap code.
      Parameters:
      tid - Transaction Identifier
      value -
      path -
      Throws:
      IOException
      ConfException

    • sharedSetElem

      public void sharedSetElem(int tid, String value, String fmt, Object... arguments) throws IOException, ConfException
      Set value to a leaf node from NCS FastMap code.
      Parameters:
      tid - Transaction Identifier
      value -
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException

    • create

      public void create(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Create a new list entry in the XML tree. For example 
       maapi.create(tid, "/servers/server{www}");
      If we are creating a new server element as above, we must also populate all other XML elements below, which do not have a default value in the YANG model. Thus we must also: 
       maapi.setElem(tid, "80",
               "/servers/server{www}/port");
      before we try to commit the data.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      ConfException - if the object already exists
      IOException

    • create

      public void create(int tid, ConfPath path) throws IOException, ConfException
      Create an entity in the XML tree. Things that can be created are liste entries, presence containers and leaves with type empty. 
       maapi.create(tid, "/servers/server{www}");
      If we are creating a new server element as above, we must also populate all other XML elements below which do not have a default value in the YANG model. Thus, assuming 'port' is mandatory we must also: 
       maapi.setElem(tid, "80",
               "/servers/server{www}/port");
      before we try to commit the data.
      Parameters:
      tid - Transaction Identifier
      path -
      Throws:
      ConfException - if the object already exists
      IOException

    • safeCreate

      public void safeCreate(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Create a new entity in the XML tree. This is variant of the create() method that doesn't throw an exception if the object already exists.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      ConfException
      IOException

    • safeCreate

      public void safeCreate(int tid, ConfPath path) throws IOException, ConfException
      Create a new list entity in the XML tree. This is variant of the create() method that doesn't throw an exception if the object already exists.
      Parameters:
      tid - Transaction Identifier
      path -
      Throws:
      ConfException
      IOException

    • sharedCreate

      public void sharedCreate(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • sharedCreate

      public void sharedCreate(int tid, ConfPath path) throws IOException, ConfException
      This is the variant of create() to use from FASTMAP code. I.e NCS code that creates NCS services. The sharedCreate() method is used by NCS service code to create data in the /devices/device tree which is shared by multiple NCS servcie instances. Everything that is created, gets a reference counter associated to it, this is so that the FASTMAP algorithm shall not delete data that is still used by other service instances. Furthermore, everything that is created with this method, also get's an additional attribute set, called 'Backpointer' which points back to the service instance that created the entity in the first place. This makes it possible to look at the /devices tree and answer the question which parts of the device configurtaion was created by which service(es)
      Parameters:
      tid - Transaction Identifier
      path -
      Throws:
      ConfException
      IOException

    • delete

      public void delete(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Deletes a node and all its children from the XML data tree.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      ConfException
      IOException

    • delete

      public void delete(int tid, ConfPath path) throws IOException, ConfException
      Deletes a node and all its children from the XML data tree.
      Parameters:
      tid - Transaction Identifier
      path -
      Throws:
      ConfException
      IOException

    • deleteAll

      public void deleteAll(int th, MaapiDeleteAllFlag how) throws ConfException, IOException
      This function can be used to delete "all" configuration data within a transaction. The flag how specifies the extent of "all":

      MAAPI_DEL_SAFE Delete everything except namespaces that were exported to none (with tailf:export none). Toplevel nodes that cannot be deleted due to AAA rules are silently left in place, but descendant nodes will still be deleted if the AAA rules allow it.

      MAAPI_DEL_EXPORTED Delete everything except namespaces that were exported to none (with tailf:export none). AAA rules are ignored, i.e. nodes are deleted even if the AAA rules don't allow it.

      MAAPI_DEL_ALL Delete everything. AAA rules are ignored.

      Parameters:
      th - Transaction handle
      how - One of the flags in MaapiDeleteAllFlag, specifying 'how' to delete all
      Throws:
      ConfException
      IOException

    • safeDelete

      public void safeDelete(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Deletes a node and all its children from the XML data tree.

      Version of delete that doesn't throw an exception if the element doesn't exist

      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      ConfException
      IOException

    • insert

      public void insert(int tid, String fmt, Object... arguments) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • insert

      public void insert(int tid, boolean createBackPointer, String fmt, Object... arguments) throws IOException, ConfException
      This function inserts a new element in an ordered list of elements. The key must be of type integer, and have the attribute <indexedView>. If the inserted element already exists, all element following the element will be reordered.
      Parameters:
      tid - Transaction Identifier
      createBackPointer - When we insert items into lists that are managed by FastMap code, we always want to set this parameter to true. Since we insert into the list, effectively changing the keys the FastMap diff-sets must be updated accordingly.
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      ConfException
      IOException

    • move

      public void move(int tid, ConfKey tokey, String fmt, Object... arguments) throws IOException, ConfException
      This function moves an existing object. Renames the object using the new instance key tokey.
      Parameters:
      tid - Transaction Identifier
      tokey -
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      ConfException
      IOException

    • move

      public void move(int tid, String tokey, String fmt, Object... arguments) throws IOException, ConfException
      This function moves an existing object

      Renames the object using the new instance key tokey represented as a string.

      Parameters:
      tid - Transaction Identifier
      tokey -
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      ConfException
      IOException

    • moveOrdered

      public void moveOrdered(int tid, MoveWhereFlag where, ConfKey tokey, String fmt, Object... arguments) throws IOException, ConfException
      For a list with the YANG ordered-by user statement, this function can be used to change the order of entries, by moving one entry to a new position. When new entries in such a list are created with Maapi.create(), they are always placed last in the list. The path given by fmt and the remaining arguments identifies the entry to move, and the new position is given by the where argument: MoveWhereFlag.MOVE_FIRST Move the entry first in the list. The tokey arguments is ignored, and can be given as NULL. MoveWhereFlag.MOVE_LAST Move the entry last in the list. The tokey arguments is ignored, and can be given as NULL. MoveWhereFlag.MOVE_BEFORE Move the entry to the position before the entry given by the tokey argument. MoveWhereFlag.MOVE_AFTER Move the entry to the position after the entry given by the tokey argument.
      Parameters:
      tid - current transaction
      where - MoveWhereFlag movement flag
      tokey - key as base for relative movements
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      IOException
      ConfException

    • getCase

      public ConfTag getCase(int tid, String choice, String fmt, Object... arguments) throws IOException, ConfException
      This returns the current 'case' for a 'choice' construct.

      When we use the YANG choice statement in the data model, this method can be used to find the currently selected case, avoiding useless getElem() etc requests for nodes that belong to other cases. The fmt arguments give the path to the list entry or container where the choice is defined, and choice is the name of the choice.The case value is returned as ConfTag.

      For a choice without a mandatory true statement where no case is currently selected, the function will fail with ERR_NOEXISTS if the choice doesn't have a default case. If it has a default case, it will be returned unless the MaapiFlag.NO_DEFAULTS flag is in effect @see MaapiFlag if the flag is set, the value returned will have type ConfTagDefault.

      NOTE: The method will suppress all ERR_NOEXISTS errors this means that the method will not throw exception when ERR_NOEXISTS occurs it will print a warning message and return null.

      Parameters:
      tid - current transaction handle
      choice - name of the choice
      fmt - path string to the container or list where the choice is defined
      arguments - optional parameters for substitution in fmt
      Returns:
      ConfTag representing the current selected case or null if the case could not be determine. If NO_DEFAULTS flag is used and the default case is selected, then ConfTagDefault instance is returned.
      Throws:
      MaapiException
      IOException
      ConfException

    • getCase

      public ConfTag getCase(int tid, String choice, ConfPath path) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • revert

      public void revert(int tid) throws IOException, ConfException
      Remove all changes in the transaction.
      Parameters:
      tid -
      Throws:
      IOException
      ConfException

    • copyTree

      public void copyTree(int tid, ConfPath from, ConfPath to) throws IOException, ConfException
      copyTree(int, boolean, ConfPath, ConfPath) Equivalent to copyTree(int, boolean, ConfPath, ConfPath) with useSharedCreate set to false i.e., for use outside fastmap, without 'shared' create/set
      Throws:
      IOException
      ConfException

    • copyTree

      public void copyTree(int tid, boolean useSharedCreate, ConfPath from, ConfPath to) throws IOException, ConfException
      This function is used to copy an entire subtree in the configuration from one point to another. When we use this function in fastmap code, we usually want to set the useSharedCreate parameter to true.
      Parameters:
      tid - Transaction Identifier
      useSharedCreate -
      from -
      to -
      Throws:
      ConfException
      IOException

    • lock

      public void lock(int db) throws IOException, ConfException
      This function is used to take a lock on one of the databases.

      Only one entity may own the lock at any given time.

      You do not have to acquire the lock before you read or write to a transaction.

      This lock is also taken by the CLI when the user enters exclusive mode. Depending on the configuration different locks will be taken, ie, if the system has been configured to have a candidate, and a writable running configuration then both a lock on running and a lock on the candidate database will be acquired.

      The following locks are acquired when you enter configure exclusive mode in the CLI:

      If the system is configured with a startup db, and no writable running or candidate: lock startup

      If the system is configured with a writable running and no startup or candidate db: lock running

      If the system is configured with a writable running and a startup db, and no candidate: lock running and startup.

      If the system is configured with a writable running and a candidate db, and no startup: lock running and candidate.

      Parameters:
      db - Database to lock. Possible values are STARTUP, RUNNING, and CANDIDATE
      Throws:
      ConfException
      IOException

    • unlock

      public void unlock(int db) throws IOException, ConfException
      This function releases a lock previously acquired using the lock() method.
      Parameters:
      db - Database to unlock. Possible values are STARTUP, RUNNING, and CANDIDATE
      Throws:
      ConfException
      IOException

    • lockPartial

      public int lockPartial(int db, String[] xpaths) throws IOException, ConfException
      It is possible to manipulate partial locks on the databases, i.e. locks on a specified set of leaves and/or subtrees. The specification of what to lock is given via the xpaths array, which is populated with xpath string expressions. If the lock succeeds, lockPartial() returns a lock identifier, which is used in the unlockPartial() call.
      Parameters:
      db - Database
      xpaths - Array of xpath expressions to lock
      Returns:
      A lock identifier which is used for unlockPartial()
      Throws:
      ConfException
      IOException

    • lockPartial

      public int lockPartial(int db, String xpath) throws IOException, ConfException
      Same as lockPartial(int,String[]) except only one xpath expression is given.
      Throws:
      IOException
      ConfException

    • unlockPartial

      public void unlockPartial(int lockId) throws IOException, ConfException
      This methods releases a lock previously acquired using the lockPartial() method.
      Parameters:
      lockId - The previously specified lock identifier
      Throws:
      ConfException
      IOException

    • deref

      public ConfObject[][] deref(int tid, String fmt, Object... arguments) throws IOException, ConfException
      This method dereferences a leafref and returns a list of the objects the leafref "points" to. I.e it returns an array of keypaths. If the leafref points to a single key, the list will be of length 1. If the leafref points to either a normal leaf, or to a list key element in a list with multiple keys, the list may be longer that 1. The path must lead to a leafref element in the XML data tree.
      Parameters:
      tid - Transaction Identifier
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Throws:
      MaapiException
      IOException
      ConfException

    • isLockSet

      public int isLockSet(int db) throws IOException, ConfException
      This methods checks if a lock is taken or not. if integer /= 0 is returned it is the usid of the lock owner
      Parameters:
      db - Database to check. Possible values are Conf.DB_STARTUP, Conf.DB_RUNNING, and Conf.DB_CANDIDATE
      Throws:
      ConfException
      IOException

    • candidateValidate

      public void candidateValidate() throws IOException, ConfException
      This function validates the candidate. The function should only be used when the candidate is not owned by ConfD, i.e. when the candidate is owned by an external database.
      Throws:
      ConfException
      IOException

    • deleteConfig

      public void deleteConfig(int db) throws IOException, ConfException
      This function empties a data store.
      Throws:
      ConfException
      IOException

    • candidateCommit

      public void candidateCommit() throws IOException, ConfException
      This function copies the candidate to running. It is also used to confirm a previous call to candidateConfirmedCommit(), i.e. to prevent the automatic rollback if a confirmed commit is not confirmed.
      Throws:
      ConfException
      IOException

    • candidateConfirmedCommit

      public void candidateConfirmedCommit(int t) throws IOException, ConfException
      This method also copies the candidate into running. However if a call to candidateCommit() is not done within a given timeout an automatic rollback will occur.
      Parameters:
      t - Timeout in seconds
      Throws:
      ConfException
      IOException

    • candidateReset

      public void candidateReset() throws IOException, ConfException
      This function copies running into candidate.
      Throws:
      ConfException
      IOException

    • candidateAbortCommit

      public void candidateAbortCommit() throws IOException, ConfException
      This function cancels a pending confirmed commit.
      Throws:
      ConfException
      IOException

    • confirmedCommitInProgress

      public int confirmedCommitInProgress() throws IOException, ConfException
      Checks whether a confirmed commit is pending. Returns the ID of the user session currently having a pending confirmed commit operation in progress or 0 if no operation is in progress.
      Throws:
      ConfException
      IOException

    • candidateConfirmedCommitPersistent

      public void candidateConfirmedCommitPersistent(int timeoutsecs, String persist, String persistId) throws IOException, ConfException
      This method can be used to start or extend a persistent confirmed commit, see the Tail-f Commit Capability section in the NETCONF Server chapter in the User Guide.

      The persist parameter sets the cookie for the persistent confirmed commit, while the persistId gives the cookie for an already ongoing persistent confirmed commit. This gives the following possibilities:

      • persist = "cookie", persistId = null Start a persistent confirmed commit with the cookie "cookie", or extend an already ongoing non-persistent confirmed commit and turn it into a persistent confirmed commit.

      • persist = "newcookie", persistId = "oldcookie" Extend an ongoing persistent confirmed commit that uses the cookie "oldcookie" and change the cookie to "newcookie".

      • persist = null, persistId = "cookie" Extend an ongoing persistent confirmed commit that uses the cookie "oldcookie" and turn it into a non-persistent confirmed commit.

      • persist = null, persistId = null Does the same as candidateConfirmedCommit(int).

      Typical usage is to start a persistent confirmed commit with persist = "cookie", persistId = null, and to extend it with persist = "cookie", persistId = "cookie". Throws ConfException
      Parameters:
      timeoutsecs - timeout for the confirmed commit
      persist - value for a new persistent confirmed commit
      persistId - value for an already ongoing persistent confirmed commit
      Throws:
      IOException
      ConfException - If error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persistId did not give the right cookie for it.

    • candidateConfirmedCommitInfo

      public void candidateConfirmedCommitInfo(int timeoutsecs, String label, String comment) throws IOException, ConfException
      This method does the same as candidateConfirmedCommitPersistent(int, java.lang.String, java.lang.String), but allows for setting the "Label" and/or "Comment" that is stored in the rollback file when the candidate is committed to running. To set only the "Label", give comment as null, and to set only the "Comment", give label as null. Note: To ensure that the "Label" and/or "Comment" are stored in the rollback file in all cases when doing a confirmed commit, they must be given both with the confirmed commit (using this method) and with the confirming commit (using candidateCommitInfo(java.lang.String, java.lang.String)).
      Parameters:
      timeoutsecs - timeout for the confirmed commit
      label - value for "Label" in the rollback file
      comment - value for "Comment" in the rollback file
      Throws:
      IOException
      ConfException - If error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persistId did not give the right cookie for it.

    • candidateConfirmedCommitInfo

      public void candidateConfirmedCommitInfo(int timeoutsecs, String persist, String persistId, String label, String comment) throws IOException, ConfException
      This method does the same as candidateConfirmedCommitPersistent(int, java.lang.String, java.lang.String), but allows for setting the "Label" and/or "Comment" that is stored in the rollback file when the candidate is committed to running. To set only the "Label", give comment as null, and to set only the "Comment", give label as null. Note: To ensure that the "Label" and/or "Comment" are stored in the rollback file in all cases when doing a confirmed commit, they must be given both with the confirmed commit (using this method) and with the confirming commit (using candidateCommitInfo(java.lang.String, java.lang.String)).
      Parameters:
      timeoutsecs - timeout for the confirmed commit
      persist - value for a new persistent confirmed commit
      persistId - value for an already ongoing persistent confirmed commit
      label - value for "Label" in the rollback file
      comment - value for "Comment" in the rollback file
      Throws:
      IOException
      ConfException - If error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persistId did not give the right cookie for it.

    • candidateAbortCommitPersistent

      public void candidateAbortCommitPersistent(String persistId) throws IOException, ConfException
      Cancel an ongoing persistent commit with the cookie given by persistId. (If persistId is null, it does the same as candidateAbortCommit().
      Parameters:
      persistId - cookie for ongoing persistent confirmed commit
      Throws:
      IOException
      ConfException - If error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persistId did not give the right cookie for it.

    • candidateCommitPersistent

      public void candidateCommitPersistent(String persistId) throws IOException, ConfException
      Confirm an ongoing persistent commit with the cookie given by persistId. (If persistId is null, it does the same as candidateCommit(). Throws ConfException if error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persist_id did not give the right cookie for it.
      Parameters:
      persistId -
      Throws:
      IOException
      ConfException - If error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persistId did not give the right cookie for it.

    • candidateCommitInfo

      public void candidateCommitInfo(String label, String comment) throws IOException, ConfException
      This method can be used to set the "Label" and/or "Comment" that is stored in the rollback file when the candidate is committed to running. To set only the "Label", give comment as null, and to set only the "Comment", give label as null. If no confirmed commit is ongoing, persistId must not be given, and the method does a normal candidate commit, like candidateCommit(). Otherwise the method will confirm the ongoing confirmed commit. For a persistent confirmed commit, the cookie can be given by persistId if needed. Note: To ensure that the "Label" and/or "Comment" are stored in the rollback file in all cases when doing a confirmed commit, they must be given both with the confirmed commit (using candidateConfirmedCommitInfo(int, java.lang.String, java.lang.String)) and with the confirming commit (using this method).
      Parameters:
      label - value for "Label" in the rollback file
      comment - value for "Comment" in the rollback file
      Throws:
      IOException
      ConfException - If error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persistId did not give the right cookie for it.

    • candidateCommitInfo

      public void candidateCommitInfo(String persistId, String label, String comment) throws IOException, ConfException
      This method can be used to set the "Label" and/or "Comment" that is stored in the rollback file when the candidate is committed to running. To set only the "Label", give comment as null, and to set only the "Comment", give label as null. If no confirmed commit is ongoing, persistId must not be given, and the method does a normal candidate commit, like candidateCommit(). Otherwise the method will confirm the ongoing confirmed commit. For a persistent confirmed commit, the cookie can be given by persistId if needed. Note: To ensure that the "Label" and/or "Comment" are stored in the rollback file in all cases when doing a confirmed commit, they must be given both with the confirmed commit (using candidateConfirmedCommitInfo(int, java.lang.String, java.lang.String)) and with the confirming commit (using this method).
      Parameters:
      persistId - value for an already ongoing persistent confirmed commit
      label - value for "Label" in the rollback file
      comment - value for "Comment" in the rollback file
      Throws:
      IOException
      ConfException - If error. If the errorCode for the ConfException is ConfException.ERR_NOEXISTS it means that there is an ongoing persistent confirmed commit, but persistId did not give the right cookie for it.

    • copyRunningToStartup

      public void copyRunningToStartup() throws IOException, ConfException
      Copies running to startup.
      Throws:
      ConfException
      IOException

    • copy

      public void copy(int thfrom, int thto) throws IOException, ConfException
      If we open two transactions from the same user sessions but towards different data stores, such as one transaction towards the candidate and one towards running, we can copy all data from one data store to the other with this method.
      Parameters:
      thfrom -
      thto -
      Throws:
      ConfException
      IOException

    • copyPath

      public void copyPath(int fromTh, int toTh, ConfPath path) throws IOException, ConfException
      Similar to copy(int, int), but does a replacing copy only of the subtree rooted at the path given by path
      Parameters:
      fromTh -
      toTh -
      path -
      Throws:
      ConfException
      IOException

    • authenticate

      public MaapiAuthentication authenticate(String user, String passwd) throws IOException, ConfException
      If we are implementing a proprietary Management Agent with MAAPI API, the method startUserSession(String,String,String[],SocketAddress, MaapiUserSessionFlag) requires the application to tell ConfD/NCS which groups the user are member of.

      ConfD/NCS itself has the capability to authenticate users. It is possible for a MAAPI application to let ConfD/NCS authenticate the user, as per the AAA configuration in the system configuration file

      Parameters:
      user -
      passwd -
      Throws:
      ConfException
      IOException

    • authenticate2

      public MaapiAuthentication authenticate2(String user, String passwd, InetAddress srcAddr, int srcPort, String context, MaapiUserSessionFlag proto) throws IOException, ConfException
      If we are implementing a proprietary Management Agent with MAAPI API, the method startUserSession(String,String,String[],SocketAddress, MaapiUserSessionFlag) requires the application to tell ConfD/NCS which groups the user are member of.

      ConfD/NCS itself has the capability to authenticate users. It is possible for a MAAPI application to let ConfD/NCS authenticate the user, as per the AAA configuration in the system configuration file

      Parameters:
      user -
      passwd -
      srcAddr -
      srcPort -
      context -
      proto -
      Throws:
      ConfException
      IOException

    • getAuthorizationInfo

      public String[] getAuthorizationInfo(int usid) throws IOException, ConfException
      This method retrieves authorization info for a user session, i.e. the groups that the user has been assigned to.
      Throws:
      IOException
      ConfException

    • getRunningDbStatus

      public int getRunningDbStatus() throws IOException, ConfException
      Query ConfD/NCS for its consistency state.

      If a transaction fails in the commit phase, the configuration database is in in a possibly inconsistent state. This method queries ConfD/NCS on the consistency state.

      Returns:
      1 if the configuration is consistent and 0 otherwise.
      Throws:
      ConfException
      IOException

    • setRunningDbStatus

      public void setRunningDbStatus(int status) throws IOException, ConfException
      Explicitly sets the systems notion of the consistency state.
      Throws:
      ConfException
      IOException

    • requestAction

      public ConfXMLParam[] requestAction(ConfXMLParam[] params, String fmt, Object... arguments) throws IOException, ConfException
      Invokes an action defined in the data model annotated with tailf:action (see tailf_yang_extensions(5)).

      The input parameters is specified as ConfXMLParam as the input array param which corresponds to the input section of the action.

      The output parameters returned from the method call returns a array of ConfXMLParam which corresponds to the output section of the action. Consider the following yang model: 

       module cs {
     namespace "http://example.com/test/cs/1.0";
     prefix cs;
     import tailf-common {
         prefix tailf;
     }

     typedef math_op {
         type enumeration {
             enum add;
             enum sub;
             enum mul;
             enum div;
             enum square;
         }
     }

     container system {
         list computer {
             key name;
             leaf name {
                 type string;
             }
             tailf:action math {
                 tailf:actionpoint math_cs;
                 input {
                     list operation {
                         min-elements 1;
                         max-elements 3;
                         leaf number {
                             type int32;
                             mandatory true;
                         }
                         leaf type {
                             type math_op;
                             mandatory true;
                         }
                         leaf-list operands {
                             type int16;
                         }
                     }
                 }
                 output {
                     container result {
                         presence "";
                         leaf number {
                             type int32;
                             mandatory true;
                         }
                         leaf type {
                             type math_op;
                             mandatory true;
                         }
                         leaf value {
                             type int16;
                             mandatory true;
                         }
                     }
                 }
             }
         }
     }
 }
      The following is a example of how to assemble the action parameters into and array of ConfXMLParam and its subclasses: 
       ConfNamespace n = new cs();
 ConfXMLParam[] params =
     new ConfXMLParam[] {
         new ConfXMLParamStart(n, cs.cs_operation_),
         new ConfXMLParamValue(n, cs.cs_number_,  new ConfInt32(13)),
         new ConfXMLParamValue(n, cs.cs_type_,    new ConfEnumeration(0)),
         new ConfXMLParamValue(n, cs.cs_operands_,
                               new ConfList(new ConfObject[] {
                                            new ConfInt16(13),
                                            new ConfInt16(25) })),
         new ConfXMLParamStop(n, cs.cs_operation_)};
      Using this we can call the action: 
       Maapi maapi = Maapi(socket);
 maapi.setNamespace(
 maapi.startUserSession("admin",
     "maapi",
     new String[] { "admin" },
     new SocketAddress(InetAddress.getLocalHost(), 0));
 //Invokes the specified action with input arguments params
 //and returns the output parameters
 ConfXMLParam[] res = maapi.requestAction(params,
                                "/system/computer{fred}/math");

      The path given by fmt and the varargs list is the full path to the action, i.e. the final element must be the name of the action element in the YANG model.

      Since actions are not associated with transactions, the namespace must be provided and the path must be absolute transactions, the namespace must be provided and the path must be absolute - but see requestActionTh(int,ConfXMLParam[],String,Object...).

      The Maapi instance must have an established user session before issue this method call.

      Parameters:
      params - action input parameters
      fmt - path string, this must be an absolute path with its root element prefixed .i.e "/prefix:tagname/...."
      arguments - optional parameters for substitution in fmt
      Returns:
      array of ConfXMLParam as the output parameters
      Throws:
      ConfException - If the methods invocation fails for some reason. The errorCode or message could be obtain through getErrorCode, getMessage()
      IOException - Signals that a I/O exception has occurred on the stream to ConfD/NCS

    • requestAction

      public ConfXMLParam[] requestAction(List<ConfXMLParam> params, String fmt, Object... arguments) throws IOException, ConfException
      Same as requestAction(ConfXMLParam[], String, Object...) with the difference that the params is List instead of ConfXMLParam array.

      The Maapi instance must have an established user session before issue this method call.

      Parameters:
      params - action input parameters as List
      fmt - path string, this must be an absolute path with its root element prefixed .i.e "/prefix:tagname/...."
      arguments - optional parameters for substitution in fmt
      Returns:
      array of ConfXMLParam as the output parameters
      Throws:
      ConfException - If the methods invocation fails for some reason. The errorCode or message could be obtain through getErrorCode, getMessage()
      IOException - Signals that a I/O exception has occurred on the stream to ConfD/NCS

    • requestAction

      public ConfXMLParam[] requestAction(ConfXMLParam[] params, int nshash, String fmt, Object... arguments) throws IOException, ConfException
      Same as requestAction(ConfXMLParam[], String, Object...) Since actions are not associated with transactions, the namespace hash nshash must be provided and the path to the action, i.e. the final element must be the name of the action in the data model. absolute - but see requestActionTh(int,ConfXMLParam[],String,Object...).
      Parameters:
      params - action parameters
      nshash - hashvalue for root namespace for the path represented by the fmt argument
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Returns:
      array of ConfXMLParam
      Throws:
      ConfException
      IOException

    • requestAction

      public ConfXMLParam[] requestAction(List<ConfXMLParam> params, int nshash, String fmt, Object... arguments) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • requestActionTh

      public ConfXMLParam[] requestActionTh(int tid, ConfXMLParam[] params, String fmt, Object... arguments) throws IOException, ConfException
      Same as requestAction(ConfXMLParam[], String, Object...) with the difference that the fmt is not required to have a namespace prefix in the root tag. The root namespace is instead retrieved from the transaction indicated by the tid argument. Also, the user session of the transaction owner is used for the action invocation. This function may be convenient in some cases where actions are invoked in conjunction with a transaction, and it must be used if the action needs to access the transaction store.
      Parameters:
      tid - current transaction handle
      params - action parameters
      fmt - path string
      arguments - optional parameters for substitution in fmt
      Returns:
      array of ConfXMLParam
      Throws:
      IOException
      ConfException

    • requestActionTh

      public ConfXMLParam[] requestActionTh(int tid, List<ConfXMLParam> params, String fmt, Object... arguments) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • snmpSendNotification

      public void snmpSendNotification(String notifName, String notifyTarget, String ctxName, SnmpVarbind[] varbinds) throws ConfException
      Send SNMP notification.

      Sends a notification to the management targets defined for 'notifyTarget' in the snmpNotifyTable in SNMP-NOTIFICATION-MIB from the specified context. If no NotifyName is specified (or if it is ""), the notification is sent to all management targets.

      Parameters:
      notifName - Notification name
      notifyTarget - Notification target name
      ctxName - Context name.
      varbinds - An array of variable bindings
      Throws:
      ConfException

    • CLIPrompt

      public String CLIPrompt(int usid, String prompt, boolean echo) throws ConfException, IOException
      Prompts user for a string.

      The echo parameter is used to control if the input should be echoed or not. If set to 'true' all input will be visible and if set to 'false' only stars will be shown instead of the actual characters entered by the user. The resulting string will be returned.

      This function is intended to be called from inside an action callback when invoked from the CLI.

      Parameters:
      usid - ID of session
      prompt - Prompt string
      echo - If the answer should be echoed or not
      Throws:
      ConfException
      IOException

    • CLIPrompt

      public String CLIPrompt(int usid, String prompt, boolean echo, int timeout) throws ConfException, IOException
      Prompts user for a string.

      The echo parameter is used to control if the input should be echoed or not. If set to 'true' all input will be visible and if set to 'false' only stars will be shown instead of the actual characters entered by the user. The resulting string will be returned.

      This function is intended to be called from inside an action callback when invoked from the CLI.

      Parameters:
      usid - ID of session
      prompt - Prompt string
      echo - If the answer should be echoed or not
      timeout - Idle timeout in seconds
      Throws:
      ConfException
      IOException

    • CLIPromptOneOf

      public String CLIPromptOneOf(int usid, String prompt, String[] choice) throws ConfException, IOException
      Prompt user for one of the strings given in the choice parameter.

      For example: 

       String res =
     maapi.CLIPromptOneOf(usid,
         "Do you want to proceed (yes/no): ",
         new String[] { "yes", "no" });
      For example: 
          Do you want to proceed (yes/no): maybe
    The value must be one of: yes,no.
    Do you want to proceed (yes/no):
      This function is intended to be called from inside an action callback when invoked from the CLI.
      Parameters:
      usid - ID of session
      prompt - Prompt string
      choice - An array of choices to accept from user
      Throws:
      ConfException
      IOException

    • CLIPromptOneOf

      public String CLIPromptOneOf(int usid, String prompt, String[] choice, int timeout) throws ConfException, IOException
      Prompt user for one of the strings given in the choice parameter.

      For example: 

       String res =
     maapi.CLIPromptOneOf(usid,
         "Do you want to proceed (yes/no): ",
         new String[] { "yes", "no" },
         60);
      For example: 
          Do you want to proceed (yes/no): maybe
    The value must be one of: yes,no.
    Do you want to proceed (yes/no):
      This function is intended to be called from inside an action callback when invoked from the CLI.
      Parameters:
      usid - ID of session
      prompt - Prompt string
      choice - An array of choices to accept from user
      timeout - Idle timeout in seconds
      Throws:
      ConfException
      IOException

    • CLIReadEOF

      public String CLIReadEOF(int usid, boolean echo) throws ConfException, IOException
      Read a multi line string from the CLI.

      The user has to end the input using ctrl-D. The entered characters will be returned. The echo parameters controls if the entered characters should be echoed or not. If set to 'true' the answer will be visible and if set to 'false' stars will be echoed instead.

      This method is intended to be called from inside an action call- back when invoked from the CLI.

      Throws:
      ConfException
      IOException

    • CLIReadEOF

      public String CLIReadEOF(int usid, boolean echo, int timeout) throws ConfException, IOException
      Read a multi line string from the CLI.

      The user has to end the input using ctrl-D. The entered characters will be returned. The echo parameters controls if the entered characters should be echoed or not. If set to 'true' the answer will be visible and if set to 'false' stars will be echoed instead.

      This function is intended to be called from inside an action call- back when invoked from the CLI.

      Throws:
      ConfException
      IOException

    • CLIWrite

      public void CLIWrite(int usid, String buf) throws ConfException, IOException
      Write to the CLI.

      This method is intended to be called from inside an action callback when invoked from the CLI.

      Parameters:
      usid - ID of session
      buf - Text to write to CLI
      Throws:
      ConfException
      IOException

    • CLIAccounting

      public void CLIAccounting(String user, int usid, String cmd) throws ConfException, IOException
      Generate an audit log entry in the CLI audit log.
      Parameters:
      user - username of session
      usid - ID of session
      cmd - Text to write to the audit log
      Throws:
      ConfException
      IOException

    • CLIDiffCmd

      public String CLIDiffCmd(int thandle, int thandleOld, ConfPath path) throws ConfException, IOException
      Get the diff between two transactions as C-/I-style CLI commands.
      Parameters:
      thandle - Transaction attached to Maapi
      thandleOld - Another transaction
      path - path
      Throws:
      ConfException
      IOException

    • CLICmdToPath

      public CLICmdToPathResult CLICmdToPath(String cmd) throws ConfException, IOException
      Equivalent to CLICmdToPath(int, String) with the first parameter set to -1 (ie, the command is not interpreted in the context of any particular transaction)
      Throws:
      ConfException
      IOException

    • CLICmdToPath

      public CLICmdToPathResult CLICmdToPath(int th, String cmd) throws ConfException, IOException
      Given a C- or I-style command, this method tries to determine the corresponding namespace and path in the schema. Returns a CLICmdToPathResult object, containing the resulting namespace and the data-model path.

      If the string cannot be interpreted as a path an exception is thrown, indicating that the string is either an operational mode command, a configuration mode command, or just badly formatted. The string is interpreted in the context of the current running configuration.

      Parameters:
      th - transaction handle
      cmd - The command to interpret
      Throws:
      ConfException
      IOException

    • CLIPathCmd

      public String CLIPathCmd(int th, EnumSet<CLIPathCmdFlag> flags, String fmt, Object... args) throws ConfException, IOException
      Returns a string representing the C/I style CLI command that can be associated with the given path.
      Parameters:
      th - Transaction handle
      flags - Flags can be given as: EMIT_PARENTS to enable the commands to reach the submode for the path to be emitted. DELETE to emit the command to delete the given path. NON_RECURSIVE to prevent that all children to a container or list item are displayed.
      fmt - path to be formatted as CLI command
      Throws:
      ConfException
      IOException

    • setReadOnlyMode

      public void setReadOnlyMode(boolean flag) throws ConfException, IOException
      Control if the node should accept write transactions
      Parameters:
      flag - Mode
      Throws:
      ConfException
      IOException

    • loadSchemas

      public MaapiSchemas loadSchemas() throws ConfException
      Load Schemas method that downloads all schemas from server into a MaapiSchemas container, from which specified schemas can be accessed and traversed.

      When loaded the MaapiSchemas object is stored locally and new calls to this method will return the same instance.

      Returns:
      MaapiSchemas object which is container for all downloaded schemas
      Throws:
      MaapiException - if loading fails
      ConfException

    • loadSchemas

      public MaapiSchemas loadSchemas(String[] namespaceURIs) throws ConfException
      Load Schemas method that downloads a specified number of schemas the server into a MaapiSchemas container, from which specified schemas can be accessed and transversed.

      When loaded the MaapiSchemas object is stored locally and new calls to this method will return the same instance.

      Parameters:
      namespaceURIs - string array of URIs for the schemas to load
      Returns:
      MaapiSchemas object which is container for all downloaded schemas
      Throws:
      MaapiException - if loading fails
      ConfException

    • getSchemas

      public static MaapiSchemas getSchemas()
      Returns the currently loaded schema.
      Returns:
      null if no schemas has been loaded.

    • reloadSchemas

      public MaapiSchemas reloadSchemas() throws ConfException
      This method throws away any old MaapiSchemas container and downloads a new from the server.

      Hence each call of this method will interact with the server.

      Returns:
      MaapiSchemas object which is container for all downloaded schemas
      Throws:
      MaapiException
      ConfException

    • reloadSchemas

      public MaapiSchemas reloadSchemas(String[] namespaceURIs) throws ConfException
      This method throws away any old MaapiSchemas container and downloads a new from the server.

      Which namespaces are loaded is specified and do not need to be the same as the earlier loaded that is viped out. This method can therefore unload old schemas and add loading of new schemas.

      Parameters:
      namespaceURIs - string array of URIs for the schemas to load
      Returns:
      MaapiSchemas object which is container for all downloaded schemas
      Throws:
      MaapiException
      ConfException

    • setUserSession

      public void setUserSession(int usid) throws ConfException, IOException
      Associate this Maapi instance with an already existing user session.

      This can be used instead startUserSession(String, String, String[], SocketAddress, MaapiUserSessionFlag) when we really do not want to start a new user session, e.g. if we want to call an action on behalf of a given user session

      Parameters:
      usid - user session id
      Throws:
      MaapiException
      ConfException
      IOException

    • loadConfigStream

      public MaapiOutputStream loadConfigStream(int tid, EnumSet<MaapiConfigFlag> flags) throws ConfException, IOException
      Load configuration from a OuputStream into ConfD/NCS.

      This method loads a configuration from a OutputStream into the server.

      The tid parameter is a transaction id. Thus the application must create and also apply the transaction. By default the complete configuration (as allowed by the user of the current transaction) is deleted before the file is loaded.

      To merge the contents of the file use the MaapiConfigFlag.MAAPI_CONFIG_MERGE flag. The MaapiConfigFlag.MAAPI_CONFIG_WITH_OPER flag can be used together with MaapiConfigFlag.MAAPI_CONFIG_XML to mean that any operational data in the file should be ignored (instead of producing an error).

      The other flags parameters are the same as for saveConfig(int, EnumSet, String, Object...)

      Parameters:
      tid - transaction id for started transaction
      flags - One of MAAPI_CONFIG_XML, MAAPI_CONFIG_J , MAAPI_CONFIG_C, MAAPI_CONFIG_WITH_DEFAULTS, MAAPI_CONFIG_SHOW_DEFAULTS, MAAPI_CONFIG_C_IOS, MAAPI_CONFIG_MERGE or MAAPI_CONFIG_WITH_OPER
      Returns:
      OutputStream to write data to.
      Throws:
      MaapiException
      ConfException
      IOException

    • loadConfig

      public void loadConfig(int tid, EnumSet<MaapiConfigFlag> flags, String filename) throws ConfException, IOException
      This function loads a configuration from filename into the server. The tid parameter is a transaction id. Thus the application must create and also apply the transaction. By default the complete configuration (as allowed by the user of the current transaction) is deleted before the file is loaded. To merge the contents of the file use the MAAPI_CONFIG_MERGE flag. The MAAPI_CONFIG_WITH_OPER flag can be used together with MAAPI_CONFIG_XML to mean that any operational data in the file should be ignored (instead of producing an error). The other flags parameters are the same as for saveConfig(int, EnumSet, String, Object...)
      Parameters:
      tid - transaction id for started transaction
      flags - One of MAAPI_CONFIG_XML, MAAPI_CONFIG_J , MAAPI_CONFIG_C, MAAPI_CONFIG_WITH_DEFAULTS, MAAPI_CONFIG_SHOW_DEFAULTS, MAAPI_CONFIG_C_IOS, MAAPI_CONFIG_MERGE or MAAPI_CONFIG_WITH_OPER
      filename - name of the configuration file relative directory where ConfD/NCS started.
      Throws:
      MaapiException
      ConfException
      IOException

    • loadConfigCmds

      public void loadConfigCmds(int tid, EnumSet<MaapiConfigFlag> flags, String cmds, String fmt, Object... arguments) throws IOException, ConfException
      This function loads a configuration from a string into the server. By default the complete configuration (as allowed by the user of the current transaction) is deleted before the file is loaded. To merge the contents of the file use the MAAPI_CONFIG_MERGE flag. The MAAPI_CONFIG_WITH_OPER flag can be used together with MAAPI_CONFIG_XML to mean that any operational data in the file should be ignored (instead of producing an error). The other flags parameters are the same as for saveConfig(int, EnumSet, String, Object...)
      Parameters:
      tid - transaction id for started transaction
      flags - One of MAAPI_CONFIG_XML, MAAPI_CONFIG_J, MAAPI_CONFIG_C, MAAPI_CONFIG_WITH_DEFAULTS, MAAPI_CONFIG_SHOW_DEFAULTS, MAAPI_CONFIG_C_IOS, MAAPI_CONFIG_MERGE or MAAPI_CONFIG_WITH_OPER
      cmds - string representing the configuration to be loaded
      fmt - path relative to which the configuration should be loaded
      Throws:
      ConfException
      IOException

    • saveConfig

      public MaapiInputStream saveConfig(int tid, EnumSet<MaapiConfigFlag> flags, ConfPath path) throws ConfException, IOException
      Save the subtree in different formats.
      Retrieves an InputStream from a given path specified by fmt with flags parameter which controls the format as follows:
      Flag Description
      Raw-XML MaapiConfigFlag.XML_FORMAT, MaapiConfigFlag.MAAPI_CONFIG_XML The configuration format is XML
      Pretty-XML MaapiConfigFlag.XML_PRETTY, MaapiConfigFlag.MAAPI_CONFIG_XML_PRETTY The configuration format is pretty printed XML
      Juniper CLI format MaapiConfigFlag.MAAPI_CONFIG_J, MaapiConfigFlag.JUNIPER_CLI_FORMAT The configuration is in curly brace Juniper CLI format
      Cisco XR CLI format MaapiConfigFlag.MAAPI_CONFIG_C_IOS, MaapiConfigFlag.CISCO_XR_FORMAT The configuration is in Cisco XR style format
      Cisco IOS CLI format MaapiConfigFlag.MAAPI_CONFIG_C_IOS, MaapiConfigFlag.CISCO_IOS_FORMAT The configuration is in Cisco IOS style format

      The provided path indicates from where the configuration is to be rooted. If for example fmt is "/aaa:aaa/authentication/users" we only dump a part of the AAA data. It must be a prefix pre pended keypath.

      By default, the treatment of nodes with a tailf:hidden statement depends on the state of the transaction. For a transaction started via MAAPI, no nodes are hidden, while for a transaction started by another northbound agent (e.g. CLI) and attached to, the nodes that are hidden are the same as in that agent session. The default can be overridden by using one of the flags MaapiConfigFlag.MAAPI_CONFIG_HIDE_ALL and MaapiConfigFlag.MAAPI_CONFIG_UNHIDE_ALL.

      By default, the NCS service-meta-data attributes (refcounter, backpointer, and original-value) are not included in the configuration. The flag MaapiConfigFlag.MAAPI_CONFIG_WITH_SERVICE_META can be used to request that these attributes should be included.

      The library will initialize a new socket to the end point specified by the initial socket (which was created during initialization of this Maapi instance) thus it is up to the use

      Parameters:
      tid - transaction id of the current transaction
      flags - format parameters (see the table above ) with additional MAAPI_CONFIG_WITH_DEFAULTS, MAAPI_CONFIG_SHOW_DEFAULTS for controlling the defaults MAAPI_CONFIG_READ_WRITE_ACCESS_ONLY for saving only nodes for which the user has read_write access
      path - path indicating where the configuration to be rooted
      Returns:
      MaapiInputStream On success
      Throws:
      ConfException - If the methods invocation fails for some reason. The errorCode or message could be obtain through getErrorCode, getMessage()
      IOException - Signals that a I/O exception has occurred on the stream to ConfD/NCS

    • saveConfig

      public MaapiInputStream saveConfig(int tid, EnumSet<MaapiConfigFlag> flags) throws ConfException, IOException
      Save the entire config in different formats.
      Retrieves an InputStream with flags parameter which controls the format as follows:
      Flag Description
      Raw-XML MaapiConfigFlag.XML_FORMAT, MaapiConfigFlag.MAAPI_CONFIG_XML The configuration format is XML
      Pretty-XML MaapiConfigFlag.XML_PRETTY, MaapiConfigFlag.MAAPI_CONFIG_XML_PRETTY The configuration format is pretty printed XML
      Juniper CLI format MaapiConfigFlag.MAAPI_CONFIG_J, MaapiConfigFlag.JUNIPER_CLI_FORMAT The configuration is in curly brace Juniper CLI format
      Cisco XR CLI format MaapiConfigFlag.MAAPI_CONFIG_C_IOS, MaapiConfigFlag.CISCO_XR_FORMAT The configuration is in Cisco XR style format
      Cisco IOS CLI format MaapiConfigFlag.MAAPI_CONFIG_C_IOS, MaapiConfigFlag.CISCO_IOS_FORMAT The configuration is in Cisco IOS style format

      By default, the treatment of nodes with a tailf:hidden statement depends on the state of the transaction. For a transaction started via MAAPI, no nodes are hidden, while for a transaction started by another northbound agent (e.g. CLI) and attached to, the nodes that are hidden are the same as in that agent session. The default can be overridden by using one of the flags MaapiConfigFlag.MAAPI_CONFIG_HIDE_ALL and MaapiConfigFlag.MAAPI_CONFIG_UNHIDE_ALL.

      Entire configuration is dumped, except that namespaces with restricted export (from 'confdc/ncsc --export') are treated as follows:

      • When the MAAPI_CONFIG_XML or MAAPI_CONFIG_XML_PRETTY formats are used, the context of the user session that started the transaction is used to select namespaces with restricted export. If the "system" context is used, all namespaces are selected, regardless of export restriction.

      • When one of the CLI formats is used, the context used to select namespaces with restricted export is always "CLI".

      The library will initialize a new socket to the end point specified by the initial socket (which was created during initialization of this Maapi instance) thus it is up to the use

      Parameters:
      tid - transaction id of the current transaction
      flags - format parameters (see the table above ) with additional MAAPI_CONFIG_WITH_DEFAULTS, MAAPI_CONFIG_SHOW_DEFAULTS for controlling the defaults
      Returns:
      MaapiInputStream On success
      Throws:
      ConfException - If the methods invocation fails for some reason. The errorCode or message could be obtain through getErrorCode, getMessage()
      IOException - Signals that a I/O exception has occurred on the stream to ConfD/NCS
      See Also:

    • saveConfig

      public MaapiInputStream saveConfig(int tid, EnumSet<MaapiConfigFlag> flags, String fmt, Object... args) throws ConfException, IOException
      Save the subtree in different formats, with ability to XPath Filtering.
      Retrieves an InputStream from a given path specified by fmt with flags parameter which controls the format as follows:
      Flag Description
      Raw-XML MaapiConfigFlag.XML_FORMAT, MaapiConfigFlag.MAAPI_CONFIG_XML The configuration format is XML
      Pretty-XML MaapiConfigFlag.XML_PRETTY, MaapiConfigFlag.MAAPI_CONFIG_XML_PRETTY The configuration format is pretty printed XML
      Juniper CLI format MaapiConfigFlag.MAAPI_CONFIG_J, MaapiConfigFlag.JUNIPER_CLI_FORMAT The configuration is in curly brace Juniper CLI format
      Cisco XR CLI format MaapiConfigFlag.MAAPI_CONFIG_C_IOS, MaapiConfigFlag.CISCO_XR_FORMAT The configuration is in Cisco XR style format
      Cisco IOS CLI format MaapiConfigFlag.MAAPI_CONFIG_C_IOS, MaapiConfigFlag.CISCO_IOS_FORMAT The configuration is in Cisco IOS style format

      The provided path indicates from where the configuration is to be rooted. If for example fmt is "/aaa:aaa/authentication/users" we only dump a part of the AAA data. It must be a prefix pre pended keypath.

      By default, the treatment of nodes with a tailf:hidden statement depends on the state of the transaction. For a transaction started via MAAPI, no nodes are hidden, while for a transaction started by another northbound agent (e.g. CLI) and attached to, the nodes that are hidden are the same as in that agent session. The default can be overridden by using one of the flags MaapiConfigFlag.MAAPI_CONFIG_HIDE_ALL and MaapiConfigFlag.MAAPI_CONFIG_UNHIDE_ALL.

      For MAAPI_CONFIG_XML and MAAPI_CONFIG_XML_PRETTY it is alternatively possible to give an XPath filter, by including the flag MaapiConfigFlag.MAAPI_CONFIG_XPATH.

      The library will initialize a new socket to the end point specified by the initial socket (which was created during initialization of this Maapi instance) thus it is up to the user to close the returning InputStream after reading the configuration.

      Parameters:
      tid - transaction id of the current transaction
      flags - format parameters (see the table above ) with additional MAAPI_CONFIG_WITH_DEFAULTS, MAAPI_CONFIG_SHOW_DEFAULTS for controlling the defaults
      fmt - path indicating where the configuration to be rooted
      args - variable argument list for c-style parameters in fmt
      Returns:
      MaapiInputStream On success the library will initialize a new socket which is intended to be closed after usage of this method by the user
      Throws:
      ConfException - If the methods invocation fails for some reason. The errorCode or message could be obtain through getErrorCode, getMessage()
      IOException - Signals that a I/O exception has occurred on the stream to ConfD/NCS
      See Also:

    • rollbackConfig

      public MaapiInputStream rollbackConfig(int tid, String fmt, String... args) throws MaapiException
      This function can be used to save the equivalent of a rollback file for a given configuration before it is committed (or a subtree thereof) in curly bracket format. The provided path indicates where we want the configuration to be rooted. It must be a prefix pre pended keypath. If fmt is null, a rollback config for the entire configuration is dumped. If for example fmt is "/aaa:aaa/authentication/users" we create a rollback config for a part of the AAA data. It is not possible to extract non-config data using this function. The data is returned as a MaapiInputStream that is used to download the configuration @see MaapiInputStream
      Parameters:
      tid - transaction id for current transaction
      fmt - path indicating where the configuration to be rooted
      args - variable argument list for c-style parameters in fmtPath
      Returns:
      MaapiInputStream
      Throws:
      MaapiException

    • isCandidateModified

      public boolean isCandidateModified() throws IOException, ConfException
      Returns true if candidate has been modified, i.e if there are pending non committed changes to the candidate data store. false if it has not been modified.
      Returns:
      boolean
      Throws:
      IOException
      ConfException

    • reportProgress

      public void reportProgress(int tid, Maapi.Verbosity verbosity, String msg) throws IOException, ConfException
      Report progress of an action or transaction.
      Parameters:
      tid - transaction handle
      verbosity - at which verbosity level the message should be reported
      msg - the message to report
      Throws:
      IOException
      ConfException

    • event

      public void event(int tid, Maapi.Verbosity verbosity, String msg, ConfPath path, Attributes attributes) throws IOException, InvalidParameterException, ConfException
      Create a progress event. This is the low level method that communicates with the progress trace framework to create events. It is recommended to use ProgressTrace.event(java.lang.String) instead.
      Parameters:
      tid - the transasction ID
      verbosity - the verbosity of the message
      msg - the message content
      path - the path of the service
      attributes - attribute of the event
      Throws:
      IOException
      ConfException
      InvalidParameterException

    • startSpan

      public Span startSpan(int tid, Maapi.Verbosity verbosity, String msg, ConfPath path, Attributes attributes, Span[] links) throws IOException, InvalidParameterException, ConfException
      Create a progress span. This is the low level method that communicates with the progress trace framework to create spans. It is recommended to use ProgressTrace.startSpan(java.lang.String) instead.
      Parameters:
      tid - the transasction ID
      verbosity - the verbosity of the message
      msg - the message content
      path - the path of the service
      attributes - attribute of the event
      links - lists of spans that this span links to
      Throws:
      IOException
      ConfException
      InvalidParameterException

    • endSpan

      public Span endSpan(Span span, String annotation) throws IOException, ConfException
      End progress span. This is the low level method that communicates with the progress trace framework to end spans. It is recommended to use ProgressTrace.endSpan(com.tailf.progress.Span) instead.
      Parameters:
      span - the span returned from startSpan(int,com.tailf.maapi.Maapi.Verbosity,java.lang.String,com.tailf.conf.ConfPath,com.tailf.progress.Attributes,com.tailf.progress.Span[])
      annotation - annotation of the ending span
      Throws:
      IOException
      ConfException

    • ncsTemplates

      public Set<String> ncsTemplates() throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • ncsApplyTemplate

      public void ncsApplyTemplate(int tid, String template, ConfPath rootIKP, Properties variables, boolean createShared) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • ncsApplyTemplate

      public void ncsApplyTemplate(int tid, String template, ConfPath rootIKP, Properties variables, String document, boolean createShared) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • ncsGetTemplateVariables

      public String[] ncsGetTemplateVariables(String template) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • initUpgrade

      public void initUpgrade(int timeoutsecs, int flags) throws IOException, ConfException
      Note, This method is only applicable for Confd. For NCS, the In-service Data Model Upgrades are directly correlated to NCS packages and have more high-level support. This is the first of three functions that must be called in sequence to perform an in-service data model upgrade, i.e. replace fxs files etc without restarting the server. See the In-service Data Model Upgrade chapter in the Confd User Guide for a detailed description of this procedure. This function initializes the upgrade procedure. The timeoutsecs parameter specifies a maximum time to wait for users to voluntarily exit from "configure mode" sessions in CLI and Web UI. If transactions are still active when the timeout expires, the function throw an ConfException. If the flag MAAPI_UPGRADE_KILL_ON_TIMEOUT was given via the flags parameter, such transactions will instead be forcibly terminated, allowing the initialization to complete successfully.
      Parameters:
      timeoutsecs - specifies a maximum time to wait for users to exit
      flags - bitflags for control of upgrade behavior
      Throws:
      IOException
      ConfException

    • performUpgrade

      public void performUpgrade(String[] loadpathdirs) throws IOException, ConfException
      Note, This method is only applicable for Confd. For NCS, the In-service Data Model Upgrades are directly correlated to NCS packages and have more high-level support. When initUpgrade() has completed successfully, this function must be called to instruct the server to load the new data model files. The loadpathdirs parameter is an array of n strings that specify the directories to load from.
      Parameters:
      loadpathdirs - array of directories
      Throws:
      IOException
      ConfException

    • commitUpgrade

      public void commitUpgrade() throws IOException, ConfException
      Note, This method is only applicable for Confd. For NCS, the In-service Data Model Upgrades are directly correlated to NCS packages and have more high-level support. When also performUpgrade() has completed successfully, this function must be called to make the upgrade permanent. This includes committing the CDB upgrade transaction when CDB is used, and we can thus get all the different exceptions that can otherwise result from applyTrans(). When commitUpgrade() has completed successfully, the program driving the upgrade must also make sure that the loadpath elements in confd.conf reference the new directories.
      Throws:
      IOException
      ConfException

    • abortUpgrade

      public void abortUpgrade() throws IOException, ConfException
      Note, This method is only applicable for Confd. For NCS, the In-service Data Model Upgrades are directly correlated to NCS packages and have more high-level support. Calling this function at any point before the call of commitUpgrade() will abort the upgrade. Note! abortUpgrade() should NOT be called if any of the three previous functions fail - in that case, the server will do an internal abort of the upgrade.
      Throws:
      IOException
      ConfException

    • getAttrs

      public ConfAttributeValue[] getAttrs(int tid, ConfAttributeType[] attribs, String fmt, Object... args) throws IOException, ConfException
      Retrieve attributes for a configuration node. These attributes are currently supported: ConfAttributeType.TAGS (values are ConfList of ConfBuf) ConfAttributeType.ANNOTATION (value is ConfBuf) ConfAttributeType.INACTIVE (not used) ConfAttributeType.ORIGIN (value is ConfIdentityRef) The attribs parameter is an array of ConfAttributeType objects, specifying the wanted attributes - if the array is empty or attribs is null, all attributes are retrieved. If no attributes are found, the returned ConfAttributeValue array is empty otherwise the result array is populated.
      Parameters:
      tid - current transaction
      attribs - array of ConfAttributeType denoting attributes to retrieve
      fmt - path indicating node to retrieve attributes from
      args - variable argument list for c-style parameters in fmtPath
      Returns:
      ConfAttributeValue[]
      Throws:
      IOException
      ConfException

    • setAttr

      public void setAttr(int tid, ConfAttributeValue attr, String fmt, Object... args) throws IOException, ConfException
      Set an attribute for a configuration node. See getAttrs() above for the supported attributes. if the attribute should be removed the ConfAttributeValue should be set attr.isRemoveValue()
      Parameters:
      tid - current transaction
      attr - ConfAttributeValue object denoting the attribute to set
      fmt - path indicating node to retrieve attributes from
      args - variable argument list for c-style parameters in fmtPath
      Throws:
      IOException
      ConfException

    • setFlags

      public void setFlags(int tid, EnumSet<MaapiFlag> flags) throws IOException, ConfException
      This method can modify some aspects of the read/write session, see MaapiFlag The flags are an Enumset of MaapiFlag
      Parameters:
      tid - current transaction
      flags - Enumset of MaapiFlag
      Throws:
      IOException
      ConfException

    • getCwd

      public String getCwd(int tid) throws IOException, ConfException
      Returns the current position as previously set by Maapi.cd(), Maapi.pushd(), or Maapi.popd() as a String. Note that what is returned is a pretty-printed version of the internal representation of the current position, it will be the shortest unique way to print the path but it might not exactly match the string given to Maapi.cd()
      Parameters:
      tid - current transaction
      Returns:
      String
      Throws:
      IOException
      ConfException

    • getCwdPath

      public ConfPath getCwdPath(int tid) throws IOException, ConfException
      Returns the current position like Maapi.getCwd(), but as a ConfPath instead of as a String.
      Parameters:
      tid - current transaction
      Returns:
      ConfPath
      Throws:
      IOException
      ConfException

    • isRunningModified

      public boolean isRunningModified() throws IOException, ConfException
      Returns true if running has been modified since the last copy to startup, false if it has not been modified.
      Returns:
      boolean
      Throws:
      IOException
      ConfException

    • doDisplay

      public boolean doDisplay(int tid, String fmt, Object... args) throws IOException, ConfException
      If the data model uses the YANG 'when' or 'tailf:display-when' statement, this function can be used to determine if the item given by the path in fmt should be displayed or not.
      Parameters:
      tid - current transaction
      fmt - path string
      args - optional parameters for substitution in fmt
      Returns:
      boolean
      Throws:
      IOException
      ConfException

    • userMessage

      public void userMessage(String to, String message, String sender) throws IOException, ConfException
      Send a message to a specific user, a specific user session or all users depending on the to parameter. If set to a user name, then message will be delivered to all CLI and Web UI sessions by that user. If set to an integer string, eg "10", then message will be delivered to that specific user session, CLI or Web UI. If set to "all" then all users will get the message.
      Parameters:
      to - username, integer string session no or "all" for all users
      message - string message to send
      sender - string
      Throws:
      IOException
      ConfException

    • sysMessage

      public void sysMessage(String to, String message) throws IOException, ConfException
      Send a message to a specific user, a specific user session or all users depending on the to parameter. If set to a user name, then message will be delivered to all CLI and Web UI sessions by that user. If set to an integer string, eg "10", then message will be delivered to that specific user session, CLI or Web UI. If set to "all" then all users will get the message. No formatting of the message is performed as opposed to the user message where a timestamp and sender information is added to the message.
      Parameters:
      to - username, integer string session no or "all" for all users
      message - string message to send
      Throws:
      IOException
      ConfException

    • prioMessage

      public void prioMessage(String to, String message) throws IOException, ConfException
      Send a high priority message to a specific user, a specific user session or all users depending on the to parameter. If set to a user name, then message will be delivered to all CLI and Web UI sessions by that user. If set to an integer string, eg "10", then message will be delivered to that specific user session, CLI or Web UI. If set to "all" then all users will get the message. No formatting of the message is performed as opposed to the user message where a timestamp and sender information is added to the message. The message will not be delayed until the user terminates any ongoing command but will be output directly to the terminal without delay. Messages sent using the maapi_sys_message and maapi_user_message, on the other hand, are not displayed in the middle of some other output but delayed until the any ongoing commands have terminated.
      Parameters:
      to - username, integer string session no or "all" for all users
      message - string message to send
      Throws:
      IOException
      ConfException

    • disconnectRemote

      public void disconnectRemote(String address) throws IOException, ConfException
      Disconnect all remote connections between CONFD_IPC_PORT (see the IPC section in the Advanced Topics chapter in the User Guide) and address. Since clients, e.g. CDB readers/subscribers, are connected using TCP it is also possible to do this remotely over a network. However since TCP does not offer a fast and reliable way of detecting that the other end has disappeared the server can get stuck waiting for a reply from such a disconnected client. In some environments there will be an alternative supervision method that can detect when a remote host is unavailable, and in that situation this function can be used to instruct the server to drop all remote connections to a particular host. The address parameter is an IP address as a string. On success, the function returns the number of connections that were closed. Note, the server will close all its sockets with remote address address, except HA connections.
      Parameters:
      address -
      Throws:
      IOException
      ConfException

    • disconnectSockets

      public void disconnectSockets(int[] sockets) throws IOException, ConfException
      This function is an alternative to disconnectRemote() that can be useful in particular when using the "External IPC" functionality (see "Using a different IPC mechanism" in the ConfD IPC section in the Advanced Topics chapter in the User Guide). In this case ConfD does not have any knowledge of the remote address of the IPC connections, and thus disconnectRemote() is not applicable. disconnectSockets() instead takes an array of file descriptor numbers as the parameter. ConfD will close all connected sockets whose local file descriptor number is included that array.
      Parameters:
      sockets - The array of socket file descriptors to close
      Throws:
      IOException
      MaapiException
      ConfException

    • getCLIInteraction

      public CLIInteraction getCLIInteraction(int usid)
      Get CLIInteraction object which enables communication with the user via the CLI. This function is intended to be called from inside an action callback when invoked from the CLI.
      Parameters:
      usid - user session id
      Returns:
      CLIInteraction

    • xpath2kpath

      public ConfPath xpath2kpath(String xpath) throws IOException, ConfException
      Convert a XPath path to a ConfPath object. The XPath expression must be an "instance identifier", i.e. all elements and keys must be fully specified. Namespace prefixes are optional, unless required to resolve ambiguities (e.g. when multiple namespaces have the same root element).
      Parameters:
      xpath -
      Returns:
      ConfPath
      Throws:
      IOException
      ConfException

    • xpath2kpath_th

      public ConfPath xpath2kpath_th(int tid, String xpath) throws IOException, ConfException
      Throws:
      IOException
      ConfException

    • xpathEval

      public void xpathEval(int tid, MaapiXPathEvalResult xpatheval, MaapiXPathEvalTrace xpathtrace, String expr, Object initstate, String fmt, Object... arguments) throws IOException, ConfException

      Evaluated the xpath expression as supplied in by expr.

      For each node in the resulting node set theresult(ConfObject[],ConfValue,Object) method of @see MaapiXPathEvalResult is called with the keypath (as ConfObject[]) to the resulting node as the first argument, and, if the node is a leaf and has a value (as ConfValue), the value of that node as the second argument otherwise it will return the string "undefined".

      The expression will be evaluated using the root node as the context node, unless a path to an existing node is given as the fmt argument.

      For each invocation the result method should return ITER_CONTINUE to tell the xpath evaluator to continue with the next resulting node. To stop the evaluation the result can return ITER_STOP instead. The MaapiXPathEvalTrace implementation of a method trace(String) that takes a single string as argument.

      If supplied (optional) it will be invoked when the xpath evaluator has trace output for the current expression.

      The initstate parameter can be used for any user supplied opaque data (i.e. whatever is supplied as initstate is passed as state to the result method for each invocation).
      Parameters:
      tid - Transaction handle
      xpatheval - A implementation of MaapiXPathEvalResult callback method
      xpathtrace - A implementation of MaapiXPathEvalTrace or null if no trace is wanted
      expr - The XPath expression
      fmt - Path string (context node) root if not supplied
      arguments - Optional parameters for substitution in fmt
      Throws:
      MaapiException - Failed MaapiXPathEvaluate
      IOException - Failed to read/write maapi socket
      ConfException

    • xpathEvalExpr

      public String xpathEvalExpr(int tid, String expr, MaapiXPathEvalTrace xpathtrace, String fmt, Object... arg) throws IOException, ConfException
      Evaluate the xpath expression given in expr parameter and return the result as a string.

      It is possible to supply a path fmt (optional) which will be treated as the initial context node when evaluating expr.

      If the path is relative, this is treated as the starting point, and this is also the node that current() will return when used in the xpath expression.

      If null is given, the current maapi position is used (set by cd(int,String,Object...))

      The MaapiXPathEvalTrace implementation of the method trace(String) which takes a single string as argument (optional) will be invoked if supplied (optional) when the xpath implementation has trace output for the current expression.

      Parameters:
      tid - Transaction handle
      expr - The xpath expression
      xpathtrace - A implementation of MaapiXPathEvalTrace or null if no trace is wanted A implementation of MaapiXPathEvalTrace or null if no trace is wanted
      fmt - Path string (context node) root if not supplied
      arg - Optional parameters for substitution in fmt
      Throws:
      ConfException - Failed MaapiXPathEvaluate
      IOException - Failed to read/write maapi socket

    • netconfSSHCallHome

      public void netconfSSHCallHome(ConfObject host, int port) throws IOException, ConfException
      Request that ConfD daemon initiates a NETCONF SSH Call Home connection (see RFC 8071) to the NETCONF client running on host.
      Parameters:
      host - The ip address or hostname of the client
      port - The port the client listens to
      Throws:
      IOException
      ConfException

    • netconfSSHCallHomeOpaque

      public void netconfSSHCallHomeOpaque(ConfObject host, String opaque, int port) throws IOException, ConfException
      Request that ConfD daemon initiates a NETCONF SSH Call Home connection (see RFC 8071) to the NETCONF client running on host.
      Parameters:
      host - The ip address or hostname of the client
      opaque - String passed to an external SSH Call Home session
      port - The port the client listens to
      Throws:
      IOException
      ConfException

    • aaaReload

      public void aaaReload(boolean synchronous) throws IOException, ConfException
      When the ConfD/NCS AAA tree is populated by an external data provider, this method can be used by the data provider to notify ConfD/NCS when there is a change to the AAA data. I.e. it is an alternative to executing the command confd --clear-aaa-cache or ncs --clear-aaa-cache.
      Parameters:
      synchronous - Whether to wait for the daemon to complete reloading the AAA data before returning.
      Throws:
      IOException
      ConfException

    • snmpaReload

      public void snmpaReload(boolean synchronous) throws IOException, ConfException
      When the ConfD/NCS SNMP Agent config tree is implemented by an external data provider, this method can be used by the data provider to notify ConfD/NCS when there is a change to the data.
      Parameters:
      synchronous - Whether to wait for the daemon to complete reloading the data before returning.
      Throws:
      IOException
      ConfException

    • startPhase

      public void startPhase(int phase, boolean synchronous) throws IOException, ConfException
      Once the ConfD/NCS daemon has been started in phase0 it is possible to use this function to tell the daemon to proceed to start phase 1 or 2.
      Parameters:
      phase - Which start phase to proceed to, 1 or 2
      synchronous - Whether to wait for the daemon to complete the transition to the requested start phase or return immediately.
      Throws:
      IOException
      ConfException

    • startPhase

      public void startPhase(int phase) throws IOException, ConfException
      Once the ConfD/NCS daemon has been started in phase0 it is possible to use this function to tell the daemon to proceed to startPhase 1 or 2. Upon return the daemon has completed the transition.
      Parameters:
      phase - Which start phase to proceed to, 1 or 2
      Throws:
      IOException
      ConfException

    • waitStart

      public void waitStart(int phase) throws IOException, ConfException
      Wait until the daemon has completed a certain start phase.
      Parameters:
      phase - Which start phase to wait for: 0, 1, or 2
      Throws:
      IOException
      ConfException

    • waitStarted

      public void waitStarted() throws IOException, ConfException
      Wait until the daemon is fully started, i.e. has completed start phase 2.
      Throws:
      IOException
      ConfException

    • reloadConfig

      public void reloadConfig() throws IOException, ConfException
      Request that the daemon reloads its configuration files. The daemon will also close and re-open its log-files.
      Throws:
      IOException
      ConfException

    • reopenLogs

      public void reopenLogs() throws IOException, ConfException
      Request that the daemon closes and re-opens its log files
      Throws:
      IOException
      ConfException

    • stop

      public void stop(boolean synchronous) throws IOException, ConfException
      Stops the daemon. Upon return the connection to the daemon will be closed.
      Parameters:
      synchronous - Whether to wait for the daemon to stop
      Throws:
      IOException
      ConfException

    • stop

      public void stop() throws IOException, ConfException
      Requests that the daemon stops, returns when daemon has stopped.
      Throws:
      IOException
      ConfException

    • getSocket

      public Socket getSocket()

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • getAutoNsList

      public static ArrayList<ConfNamespace> getAutoNsList()
      Returns:
      the currently auto generated namespace list.

    • getAutoNsMap

      public static Map<Integer,ConfNamespace> getAutoNsMap()
      Returns:
      the currently auto generated namespace map keyed on the namespace hash.

    • getAutoNsPrefixMap

      public static Map<String,List<ConfNamespace>> getAutoNsPrefixMap()
      Returns:
      the currently auto generated namespace prefix map. The namespace prefix map maps namespace prefixes to namespaces.

    • getAutoNsList

      public static ArrayList<ConfNamespace> getAutoNsList(List<ConfNamespace> defaultNsList)
      Returns:
      the currently auto generated namespace list or supplied default if no auto generated exists.

    • queryStart

      public <T extends ResultType> QueryResult<T> queryStart(int tid, String expr, String context, int chunkSize, int offset, List<String> select, List<String> sort, boolean reverseSortOrder, Class<T> cls) throws IOException, ConfException
      Initiate (or starts) a new XPath query attached to the transaction given in th.

      If successful a QueryResult is returned which represents a query result.

      The XPath expr string parameter is a primary XPath expression which must evaluate to a node-set, the "results". For each node in the results node-set every "select" expression is evaluated with the result node as its context. For example, given the YANG snippet: 

           list interface {
         key name;
         unique number;
         leaf name {
           type string;
         }
         leaf number {
           type uint32;
           mandatory true;
         }
         leaf enabled {
           type boolean;
           default true;
         }
       ...
       }
      and given that we want to find the name and number of all enabled interfaces - the expr could be "/interface[enabled='true']", and the select expressions would be { "name","number" }.

      Note that the select expressions can have any valid XPath expression, so if you wanted to find out an interfaces name, and whether its number is even or not, the expressions would be: { "name", "(number mod 2) == 0" } .

      The select parameter determining what to include in the result.

      The chunksize is the possibility to return the result in groups of a particular size. This option determines the fetch frequency for a iterator.

      The "chunk" retrieval is done by the QueryResult.iterator() iterator which process result locally and when it needs more data it retrieve the next chunk (if available).

      The offset is the number of the first result in this chunk (i.e. for the first chunk it will be 1).

      If the underlying database supports multiple "tables" there is usually also support for "join" (the ability to make a filter span several tables), in ConfD/NCS this is usually not an issue - reference to "other" tables are naturally done using leafref, and thus it is possible to filter on "foreign keys" (to use SQL terminology).

      Parameters:
      tid - transaction handle
      expr - XPath expression
      context - A context node
      chunkSize - Result chunksize to fetch
      offset - The offset to start fetch
      select - A list of XPath "select" expressions
      sort - A list of XPath exressions used for sorting
      reverseSortOrder - Set this to true to get items in the reverse order (only if "sort" is specified)
      cls - Result type
      Returns:
      A QueryResult where resulting nodes and values could be fetched.
      Throws:
      IOException - if the underlying socket or input stream is closed for some reason
      ConfException - if the XPath parser encounters error for some reason

    • queryStart

      public <T extends ResultType> QueryResult<T> queryStart(int tid, String expr, String context, int chunkSize, int offset, List<String> select, Class<T> cls) throws IOException, ConfException
      Initiate (or starts) a new XPath query attached to the transaction given in tid.

      Runs an XPath query with default sort order

      If successful a QueryResult is returned which represents a query result.

      Parameters:
      tid - transaction handle
      expr - XPath expression
      context - A context node
      chunkSize - Result chunksize to fetch
      offset - The offset to start fetch
      select - A list of XPath "select" expressions
      cls - Result type
      Returns:
      A QueryResult where resulting nodes and values could be fetched.
      Throws:
      IOException - if the underlying socket or input stream is closed for some reason
      ConfException - if the XPath parser encounters error for some reason

    • setDelayedWhen

      public boolean setDelayedWhen(int tid, boolean on) throws IOException, ConfException
      This function enables/disables the "delayed when" mode of a transaction. When successful, it returns true/false as indication of whether "delayed when" was enabled or disabled before the call. The YANG when statement makes its parent data definition statement conditional. This can be problematic in cases where we don't have control over the order of writing different data nodes. E.g. when loading configuration from a file, the data that will satisfy the when condition may occur after the data that the when applies to, making it impossible to actually write the latter data into the transaction - since the when isn't satisifed, the data nodes effectively do not exist in the schema. This is addressed by the "delayed when" mode for a transaction. When "delayed when" is enabled, it is possible to write to data nodes even though they are conditional on a when that isn't satisfied. It has no effect on reading though - trying to read data that is conditional on an unsatisfied when will always result in ConfNoExists value or equivalent. When disabling "delayed when", any "delayed" when statements will take effect immediately - i.e. if the when isn't satisfied at that point, the conditional nodes and any data values for them will be deleted. If we don't explicitly disable "delayed when" by calling this function, it will be automatically disabled when the transaction enters the VALIDATE state (e.g. due to call of applyTrans(int, boolean).
      Parameters:
      tid - transaction id
      on - true if "delayed when" mode should be activated, false if "delayed when" mode should be deactivated.
      Returns:
      true if "delayed when" was active before this call, otherwise false
      Throws:
      IOException
      ConfException

    • clearOpCache

      public void clearOpCache() throws IOException, ConfException
      Same as clearOpCache(ConfPath), with the only difference that if clears all cached data from "/" and down.
      Throws:
      IOException
      ConfException

    • clearOpCache

      public void clearOpCache(ConfPath path) throws IOException, ConfException
      Request clearing of the operational data cache (see the Operational Data the User Guide). A ConfPath argument is given to the top of the subtree for which cached data should be cleared
      Parameters:
      path - ConfPath to the subtree for which cached data should be cleared
      Throws:
      IOException
      ConfException

    • getMountId

      public List<String> getMountId(int tid, ConfPath path) throws ConfException
      Throws:
      ConfException

    • getSource

      public static InetAddress getSource(SocketAddress address) throws UnknownHostException
      Throws:
      UnknownHostException

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • hideGroup

      public void hideGroup(int tid, String groupName) throws IOException, ConfException
      Hide all nodes belonging to a hide group in a transaction that started with MaapiFlag.HIDE_ALL_HIDEGROUPS flag.
      Parameters:
      tid - Transaction Identifier
      groupName - Group Name
      Throws:
      MaapiException
      IOException
      ConfException

    • unhideGroup

      public void unhideGroup(int tid, String groupName) throws IOException, ConfException
      Unhide all nodes belonging to a hide group in a transaction that started with MaapiFlag.HIDE_ALL_HIDEGROUPS flag.
      Parameters:
      tid - Transaction Identifier
      groupName - Group Name
      Throws:
      MaapiException
      IOException
      ConfException