framework/src/main/java/org/opendaylight/protocol/framework/ProtocolInputStream.java

   1 /*
   2  * Copyright (c) 2013 Cisco Systems, Inc. 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.protocol.framework;
   9
  10 import java.io.IOException;
  11
  12 /**
  13  * Data stream interface between Protocol Message and byte array, that represents this message as Java object. Used by
  14  * the Dispatcher.
  15  */
  16 public interface ProtocolInputStream {
  17
  18         /**
  19          * Check availability of a message in underlying input stream. A message is available when there are more or the
  20          * same amount of bytes in the stream as the message length is specified in message header. If there are not enough
  21          * bytes for the message or even to read a message header, return false. Needs to be synchronized.
  22          *
  23          * @return true if there are enough bytes to read a message false if there are not enough bytes to read a message or
  24          *         a message header.
  25          *
  26          * @throws IOException this exception may be thrown when "impossible" protocol buffering conditions occur.
  27          *         Examples include: we are attempting to wait for more data than is theoretically possible (e.g. framing
  28          *         error), peer is attempting to make us buffer more data than possible to accomodate (2G chunk), etc.
  29          */
  30         public boolean isMessageAvailable() throws IOException;
  31
  32         /**
  33          * If there are enough bytes in the underlying stream, parse the message. Blocking, till there are enough bytes to
  34          * read, therefore the call of method isMessageAvailable() is suggested first. Needs to be synchronized.
  35          *
  36          * @return protocol specific message
  37          *
  38          * @throws DeserializerException if the parsing was not successful due to syntax error
  39          * @throws IOException if there was problem with extracting bytes from the stream
  40          * @throws DocumentedException if the parsing was not successful
  41          */
  42         public ProtocolMessage getMessage() throws DeserializerException, IOException, DocumentedException;
  43 }