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