//______________________________________________________________________________
//   |       |
//   | knipp |           Knipp Medien und Kommunikation GmbH
//    -------
//
//
//     Knipp RRI Toolkit
//
//
//     Copyright (C) 2005 by Knipp Medien und Kommunikation GmbH
//
//     This library is free software; you can redistribute it and/or
//     modify it under the terms of the GNU Lesser General Public License 
//     as published by the Free Software Foundation; either version 2.1 
//     of the License, or any later version.
// 
//     This library is distributed in the hope that it will be useful, 
//     but WITHOUT ANY WARRANTY; without even the implied warranty of
//     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
//     GNU Lesser General Public License for more details.
//
//     You should have received a copy of the GNU Lesser General
//     Public License along with this library; if not, write to the 
//     Free Software Foundation, Inc., 59 Temple Place, Suite 330, 
//     Boston, MA 02111-1307 USA 
//
//
//     initial author:    Klaus Malorny
//
//     version:           1.3 (15112), 2011/05/27 16:00:14
//                        $Revision: 14936 $ 
//                        $Date: 2010-11-05 15:57:40 +0100 (Fri, 05 Nov 2010) $
//                        $Author: Klaus.Malorny $
//

package de.knipp.rritoolkit;

import java.io.IOException;


/**
 *  interface to a class that implements a communication channel to the
 *  registry. Independently from the used transport technology, an 
 *  implementation must guarantee that the order of responses match the
 *  order of the requests. The implementation must be thread-safe, especially
 *  it must allow that two different threads may send messages and wait 
 *  for responses in parallel. 
 *
 *  @version  $Revision: 14936 $
 *  @author   Klaus Malorny
 */

public interface RegistryChannel
{
  /**
   *  send the given message to the registry. As the transport mechanism
   *  may need to know whether the data represents the XML or key-value form
   *  of the request, it must be specified. If the channel is already closed,
   *  an exception is thrown.
   *
   *  @param data                     the data representing the message
   *  @param isXml                    {@code true} if the message uses the
   *                                  XML encoding, {@code false} if the
   *                                  message uses key-value pairs.
   *  @throws IOException             if the transmission failed
   */
  
  public void send (byte[] data, boolean isXml)
    throws IOException;
  
  
  
  /**
   *  wait for a response from the registry.
   *
   *  @return                         the message that has been received
   *  @throws IOException             if the connection has been closed either
   *                                  before or during the call.
   */
  
  public byte[] receive ()
    throws IOException;
  
  
  
  /**
   *  return whether the channel has been closed
   *
   *  @return                     {@code true} if closed
   */
  
  public boolean isClosed ();
  
  
  
  /**
   *  close the channel. Closing an already closed channel should be
   *  ignored
   */
  
  public void close ();
  
}



 