library/impl/src/main/java/org/opendaylight/ovsdb/lib/OvsdbClient.java

   1 /*
   2  * Copyright (c) 2014, 2015 EBay Software Foundation and others. All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8
   9 package org.opendaylight.ovsdb.lib;
  10
  11 import com.google.common.util.concurrent.ListenableFuture;
  12 import java.util.List;
  13 import org.opendaylight.ovsdb.lib.message.MonitorRequest;
  14 import org.opendaylight.ovsdb.lib.message.TableUpdates;
  15 import org.opendaylight.ovsdb.lib.notation.Row;
  16 import org.opendaylight.ovsdb.lib.operations.Operation;
  17 import org.opendaylight.ovsdb.lib.operations.OperationResult;
  18 import org.opendaylight.ovsdb.lib.operations.TransactionBuilder;
  19 import org.opendaylight.ovsdb.lib.schema.DatabaseSchema;
  20 import org.opendaylight.ovsdb.lib.schema.GenericTableSchema;
  21 import org.opendaylight.ovsdb.lib.schema.TableSchema;
  22 import org.opendaylight.ovsdb.lib.schema.typed.TypedBaseTable;
  23
  24 /**
  25  * The main interface to interact with a device speaking ovsdb protocol in an asynchronous fashion and hence most
  26  * operations return a Future object representing the eventual response data from the remote.
  27  */
  28 public interface OvsdbClient {
  29
  30     /**
  31      * Gets the list of database names exposed by this ovsdb capable device.
  32      * @return list of database names
  33      */
  34     ListenableFuture<List<String>> getDatabases();
  35
  36     /**
  37      * Asynchronously returns the schema object for a specific database.
  38      * @param database name of the database schema
  39      * @return DatabaseSchema future
  40      */
  41     ListenableFuture<DatabaseSchema> getSchema(String database);
  42
  43     /**
  44      * Allows for a mini DSL way of collecting the transactions to be executed against the ovsdb instance.
  45      * @return TransactionBuilder
  46      */
  47     TransactionBuilder transactBuilder(DatabaseSchema dbSchema);
  48
  49     /**
  50      * Execute the list of operations in a single Transactions. Similar to the transactBuilder() method
  51      * @param operations List of operations that needs to be part of a transact call
  52      * @return Future object representing the result of the transaction. Calling
  53      *     cancel on the Future would cause OVSDB cancel operation to be fired against
  54      *     the device.
  55      */
  56     ListenableFuture<List<OperationResult>> transact(DatabaseSchema dbSchema, List<Operation> operations);
  57
  58     /**
  59      * ovsdb <a href="http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-04#section-4.1.5">monitor</a> operation.
  60      * @param monitorRequests represents what needs to be monitored including a client specified monitor handle. This
  61      *                       handle is used to later cancel ({@link #cancelMonitor(MonitorHandle)}) the monitor.
  62      * @param callback receives the monitor response
  63      */
  64     <E extends TableSchema<E>> TableUpdates monitor(DatabaseSchema schema,
  65                                                     List<MonitorRequest> monitorRequests,
  66                                                     MonitorCallBack callback);
  67
  68     /**
  69      * ovsdb <a href="http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-04#section-4.1.5">monitor</a> operation.
  70      * @param monitorRequests represents what needs to be monitored
  71      * @param monitorHandle  A client specified monitor handle. This handle is used to later cancel
  72      *                       ({@link #cancelMonitor(MonitorHandle)}) the monitor.
  73      * @param callback receives the monitor response
  74      */
  75     <E extends TableSchema<E>> TableUpdates monitor(DatabaseSchema schema,
  76                                                     List<MonitorRequest> monitorRequests,
  77                                                     MonitorHandle monitorHandle,
  78                                                     MonitorCallBack callback);
  79
  80     /**
  81      * Cancels an existing monitor method.
  82      * @param handler Handle identifying a specific monitor request that is being cancelled.
  83      * @throws java.lang.IllegalStateException if there is no outstanding monitor request for this handle
  84      */
  85     void cancelMonitor(MonitorHandle handler);
  86
  87     /**
  88      * ovsdb <a href="http://tools.ietf.org/html/draft-pfaff-ovsdb-proto-04#section-4.1.8">lock</a> operation.
  89      * @param lockId a client specified id for the lock; this can be used for unlocking ({@link #unLock(String)})
  90      * @param lockedCallBack Callback to nofify when the lock is acquired
  91      * @param stolenCallback Callback to notify when an acquired lock is stolen by another client
  92      */
  93     void lock(String lockId, LockAquisitionCallback lockedCallBack, LockStolenCallback stolenCallback);
  94
  95     /**
  96      * ovsdb steal operation.
  97      * See {@link #lock(String, LockAquisitionCallback, LockStolenCallback)}
  98      */
  99     ListenableFuture<Boolean> steal(String lockId);
 100
 101     /**
 102      * ovsdb unlock operation.
 103      * See {@link #unLock(String)}
 104      */
 105     ListenableFuture<Boolean> unLock(String lockId);
 106
 107     /**
 108      * ovsdb echo operation.
 109      */
 110     ListenableFuture<List<String>> echo();
 111
 112     /**
 113      * Starts the echo service. The {@code callbackFilters} can be used to get notified on the absence of echo
 114      * notifications from the remote device and control the frequency of such notifications.
 115      * @param callbackFilters callbacks for notifying the client of missing echo calls from remote.
 116      */
 117     void startEchoService(EchoServiceCallbackFilters callbackFilters);
 118
 119     /**
 120      * Stops the echo service, i.e echo requests from the remote would not be acknowledged after this call.
 121      */
 122     void stopEchoService();
 123
 124     OvsdbConnectionInfo getConnectionInfo();
 125
 126     boolean isActive();
 127
 128     void disconnect();
 129
 130     DatabaseSchema getDatabaseSchema(String dbName);
 131
 132     /**
 133      * User friendly convenient methods that make use of TyperUtils.getTypedRowWrapper to create a Typed Row Proxy
 134      * given the Typed Table Class.
 135      *
 136      * @param klazz Typed Interface
 137      * @return Proxy wrapper for the actual raw Row class.
 138      */
 139     <T extends TypedBaseTable<?>> T createTypedRowWrapper(Class<T> klazz);
 140
 141     /**
 142      * User friendly convenient methods that make use of getTypedRowWrapper to create a Typed Row Proxy given
 143      * DatabaseSchema and Typed Table Class.
 144      *
 145      * @param dbSchema Database Schema of interest
 146      * @param klazz Typed Interface
 147      * @return Proxy wrapper for the actual raw Row class.
 148      */
 149     <T extends TypedBaseTable<?>> T createTypedRowWrapper(DatabaseSchema dbSchema, Class<T> klazz);
 150
 151     /**
 152      * User friendly convenient method to get a Typed Row Proxy given a Typed Table Class and the Row to be wrapped.
 153      *
 154      * @param klazz Typed Interface
 155      * @param row The actual Row that the wrapper is operating on. It can be null if the caller
 156      *            is just interested in getting ColumnSchema.
 157      * @return Proxy wrapper for the actual raw Row class.
 158      */
 159     <T extends TypedBaseTable<?>> T getTypedRowWrapper(final Class<T> klazz,
 160                                                        final Row<GenericTableSchema> row);
 161
 162 }