openflowjava/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      * <p>
  35      * If this request fails on the remote device, {@link FutureCallback#onFailure(Throwable)}
  36      * will be called with an instance of {@link DeviceRequestFailedException}.
  37      *
  38      * <p>
  39      * If the request fails due to local reasons, {@link FutureCallback#onFailure(Throwable)}
  40      * will be called with an instance of {@link OutboundQueueException}. In particular, if
  41      * this request failed because the device disconnected, {@link OutboundQueueException#DEVICE_DISCONNECTED}
  42      * will be reported.
  43      *
  44      * @param xid Previously-reserved XID
  45      * @param message Message which should be sent out, or null if the reservation
  46      *                should be cancelled.
  47      * @param callback Callback to be invoked, or null if no callback should be invoked.
  48      * @throws IllegalArgumentException if the slot is already committed or was never reserved.
  49      */
  50     void commitEntry(
  51             @Nonnull Long xid,
  52             @Nullable OfHeader message,
  53             @Nullable FutureCallback<OfHeader> callback);
  54
  55     /**
  56      * Commit the specified offset using a message. Specified callback will
  57      * be invoked once we know how it has resolved, either with a normal response,
  58      * implied completion via a barrier, or failure (such as connection drop). For
  59      * multipart responses, {@link FutureCallback#onSuccess(Object)} will be invoked
  60      * multiple times as the corresponding responses arrive. If the request is completed
  61      * with a response, the object reported will be non-null. If the request's completion
  62      * is implied by a barrier, the object reported will be null.
  63      *
  64      * <p>
  65      * If this request fails on the remote device, {@link FutureCallback#onFailure(Throwable)}
  66      * will be called with an instance of {@link DeviceRequestFailedException}.
  67      *
  68      * <p>
  69      * If the request fails due to local reasons, {@link FutureCallback#onFailure(Throwable)}
  70      * will be called with an instance of {@link OutboundQueueException}. In particular, if
  71      * this request failed because the device disconnected, {@link OutboundQueueException#DEVICE_DISCONNECTED}
  72      * will be reported.
  73      *
  74      * @param xid Previously-reserved XID
  75      * @param message Message which should be sent out, or null if the reservation
  76      *                should be cancelled.
  77      * @param callback Callback to be invoked, or null if no callback should be invoked.
  78      * @param isComplete Function to determine if OfHeader is processing is complete
  79      * @throws IllegalArgumentException if the slot is already committed or was never reserved.
  80      */
  81     void commitEntry(
  82             @Nonnull Long xid,
  83             @Nullable OfHeader message,
  84             @Nullable FutureCallback<OfHeader> callback,
  85             @Nullable Function<OfHeader, Boolean> isComplete);
  86 }