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