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 java.util.function.Function;
  13 import javax.annotation.Nonnull;
  14 import javax.annotation.Nullable;
  15 import org.opendaylight.yang.gen.v1.urn.opendaylight.openflow.protocol.rev130731.OfHeader;
  16
  17 @Beta
  18 public interface OutboundQueue {
  19     /**
  20      * Reserve an entry in the outbound queue.
  21      * @return XID for the new message, or null if the queue is full
  22      */
  23     Long reserveEntry();
  24
  25     /**
  26      * Commit the specified offset using a message. Specified callback will
  27      * be invoked once we know how it has resolved, either with a normal response,
  28      * implied completion via a barrier, or failure (such as connection drop). For
  29      * multipart responses, {@link FutureCallback#onSuccess(Object)} will be invoked
  30      * multiple times as the corresponding responses arrive. If the request is completed
  31      * with a response, the object reported will be non-null. If the request's completion
  32      * is implied by a barrier, the object reported will be null.
  33      *
  34      * If this request fails on the remote device, {@link FutureCallback#onFailure(Throwable)}
  35      * will be called with an instance of {@link DeviceRequestFailedException}.
  36      *
  37      * If the request fails due to local reasons, {@link FutureCallback#onFailure(Throwable)}
  38      * will be called with an instance of {@link OutboundQueueException}. In particular, if
  39      * this request failed because the device disconnected, {@link OutboundQueueException#DEVICE_DISCONNECTED}
  40      * will be reported.
  41      *
  42      * @param xid Previously-reserved XID
  43      * @param message Message which should be sent out, or null if the reservation
  44      *                should be cancelled.
  45      * @param callback Callback to be invoked, or null if no callback should be invoked.
  46      * @throws IllegalArgumentException if the slot is already committed or was never reserved.
  47      */
  48     void commitEntry(
  49             @Nonnull Long xid,
  50             @Nullable OfHeader message,
  51             @Nullable FutureCallback<OfHeader> callback);
  52
  53     /**
  54      * Commit the specified offset using a message. Specified callback will
  55      * be invoked once we know how it has resolved, either with a normal response,
  56      * implied completion via a barrier, or failure (such as connection drop). For
  57      * multipart responses, {@link FutureCallback#onSuccess(Object)} will be invoked
  58      * multiple times as the corresponding responses arrive. If the request is completed
  59      * with a response, the object reported will be non-null. If the request's completion
  60      * is implied by a barrier, the object reported will be null.
  61      *
  62      * If this request fails on the remote device, {@link FutureCallback#onFailure(Throwable)}
  63      * will be called with an instance of {@link DeviceRequestFailedException}.
  64      *
  65      * If the request fails due to local reasons, {@link FutureCallback#onFailure(Throwable)}
  66      * will be called with an instance of {@link OutboundQueueException}. In particular, if
  67      * this request failed because the device disconnected, {@link OutboundQueueException#DEVICE_DISCONNECTED}
  68      * will be reported.
  69      *
  70      * @param xid Previously-reserved XID
  71      * @param message Message which should be sent out, or null if the reservation
  72      *                should be cancelled.
  73      * @param callback Callback to be invoked, or null if no callback should be invoked.
  74      * @param isComplete Function to determine if OfHeader is processing is complete
  75      * @throws IllegalArgumentException if the slot is already committed or was never reserved.
  76      */
  77     void commitEntry(
  78             @Nonnull Long xid,
  79             @Nullable OfHeader message,
  80             @Nullable FutureCallback<OfHeader> callback,
  81             @Nullable Function<OfHeader, Boolean> isComplete);
  82 }