openflow-protocol-api/src/main/java/org/opendaylight/openflowjava/protocol/api/connection/OutboundQueue.java

   1 /*
   2  * Copyright (c) 2015 Pantheon Technologies s.r.o. 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 package org.opendaylight.openflowjava.protocol.api.connection;
   9
  10 import com.google.common.annotations.Beta;
  11 import com.google.common.util.concurrent.FutureCallback;
  12 import javax.annotation.Nonnull;
  13 import javax.annotation.Nullable;
  14 import org.opendaylight.yang.gen.v1.urn.opendaylight.openflow.protocol.rev130731.OfHeader;
  15
  16 @Beta
  17 public interface OutboundQueue {
  18     /**
  19      * Reserve an entry in the outbound queue.
  20      * @return XID for the new message, or null if the queue is full
  21      */
  22     Long reserveEntry();
  23
  24     /**
  25      * Commit the specified offset using a message. Specified callback will
  26      * be invoked once we know how it has resolved, either with a normal response,
  27      * implied completion via a barrier, or failure (such as connection drop). For
  28      * multipart responses, {@link FutureCallback#onSuccess(Object)} will be invoked
  29      * multiple times as the corresponding responses arrive. If the request is completed
  30      * with a response, the object reported will be non-null. If the request's completion
  31      * is implied by a barrier, the object reported will be null.
  32      *
  33      * If this request fails on the remote device, {@link FutureCallback#onFailure(Throwable)}
  34      * will be called with an instance of {@link DeviceRequestFailedException}.
  35      *
  36      * If the request fails due to local reasons, {@link FutureCallback#onFailure(Throwable)}
  37      * will be called with an instance of {@link OutboundQueueException}. In particular, if
  38      * this request failed because the device disconnected, {@link OutboundQueueException#DEVICE_DISCONNECTED}
  39      * will be reported.
  40      *
  41      * @param xid Previously-reserved XID
  42      * @param message Message which should be sent out, or null if the reservation
  43      *                should be cancelled.
  44      * @param callback Callback to be invoked, or null if no callback should be invoked.
  45      * @throws IllegalArgumentException if the slot is already committed or was never reserved.
  46      */
  47     void commitEntry(@Nonnull Long xid, @Nullable OfHeader message, @Nullable FutureCallback<OfHeader> callback);
  48 }