library/src/main/java/org/opendaylight/ovsdb/lib/OvsDBClient.java

   1 /*
   2  *
   3  *  * Copyright (C) 2014 EBay Software Foundation
   4  *  *
   5  *  * This program and the accompanying materials are made available under the
   6  *  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   7  *  * and is available at http://www.eclipse.org/legal/epl-v10.html
   8  *  *
   9  *  * Authors : Ashwin Raveendran
  10  *
  11  */
  12
  13 package org.opendaylight.ovsdb.lib;
  14
  15 import java.util.List;
  16
  17 import org.opendaylight.ovsdb.lib.message.MonitorRequest;
  18 import org.opendaylight.ovsdb.lib.operations.Operation;
  19 import org.opendaylight.ovsdb.lib.operations.OperationResult;
  20 import org.opendaylight.ovsdb.lib.operations.TransactionBuilder;
  21 import org.opendaylight.ovsdb.lib.schema.DatabaseSchema;
  22 import org.opendaylight.ovsdb.lib.schema.TableSchema;
  23
  24 import com.google.common.util.concurrent.ListenableFuture;
  25
  26 /**
  27  * The main interface to interact with a device speaking ovsdb protocol in an asynchronous fashion and hence most
  28  * operations return a Future object representing the eventual response data from the remote.
  29  */
  30 public interface OvsDBClient {
  31
  32     /**
  33      * Gets the list of database names exposed by this ovsdb capable device
  34      * @return list of database names
  35      */
  36     ListenableFuture<List<String>> getDatabases();
  37
  38     /**
  39      * Asynchronously returns the schema object for a specific database
  40      * @param database name of the database schema
  41      * @param cacheResult if the results be cached by this instance
  42      * @return DatabaseSchema future
  43      */
  44     ListenableFuture<DatabaseSchema> getSchema(String database, boolean cacheResult);
  45
  46     /**
  47      * Allows for a mini DSL way of collecting the transactions to be executed against the ovsdb instance.
  48      * @return TransactionBuilder
  49      */
  50     TransactionBuilder transactBuilder();
  51
  52     /**
  53      * Execute the list of operations in a single Transactions. Similar to the transactBuilder() method
  54      * @param operations List of operations that needs to be part of a transact call
  55      * @return Future object representing the result of the transaction. Calling
  56      * cancel on the Future would cause OVSDB cancel operation to be fired against
  57      * the device.
  58      */
  59     ListenableFuture<List<OperationResult>> transact(List<Operation> operations);
  60
  61
  62     /**
  63      * ovsdb <a href="http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-04#section-4.1.5">monitor</a> operation.
  64      * @param monitorRequests represents what needs to be monitored including a client specified monitor handle. This
  65      *                       handle is used to later cancel ({@link #cancelMonitor(MonitorHandle)}) the monitor.
  66      * @param callback receives the monitor response
  67      */
  68     public <E extends TableSchema<E>> MonitorHandle monitor(DatabaseSchema schema, List<MonitorRequest<E>> monitorRequests,
  69                                  MonitorCallBack callback);
  70
  71     /**
  72      * Cancels an existing monitor method.
  73      * @param handler Handle identifying a specific monitor request that is being cancelled.
  74      * @throws java.lang.IllegalStateException if there is no outstanding monitor request for this handle
  75      */
  76     public void cancelMonitor(MonitorHandle handler);
  77
  78     /**
  79      * ovsdb <a href="http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-04#section-4.1.8">lock</a> operation.
  80      * @param lockId a client specified id for the lock; this can be used for unlocking ({@link #unLock(String)})
  81      * @param lockedCallBack Callback to nofify when the lock is acquired
  82      * @param stolenCallback Callback to notify when an acquired lock is stolen by another client
  83      */
  84     public void lock(String lockId, LockAquisitionCallback lockedCallBack, LockStolenCallback stolenCallback);
  85
  86     /**
  87      * ovsdb steal operation, see {@link #lock(String, LockAquisitionCallback, LockStolenCallback)}
  88      * @param lockId
  89      * @return
  90      */
  91     public ListenableFuture<Boolean> steal(String lockId);
  92
  93     /**
  94      * ovsdb unlock operaiton, see {@link #unLock(String)}
  95      * @param lockId
  96      * @return
  97      */
  98     public ListenableFuture<Boolean> unLock(String lockId);
  99
 100     /**
 101      * Starts the echo service. The {@code callbackFilters} can be used to get notified on the absence of echo
 102      * notifications from the remote device and control the frequency of such notifications.
 103      * @param callbackFilters callbacks for notifying the client of missing echo calls from remote.
 104      */
 105     public void startEchoService(EchoServiceCallbackFilters callbackFilters);
 106
 107     /**
 108      * Stops the echo service, i.e echo requests from the remote would not be acknowledged after this call.
 109      */
 110     public void stopEchoService();
 111
 112 }