/*
** Module   : Connection.java
** Abstract : high level API for a provider of a specific network transport 
**
** Copyright (c) 2009-2021, Golden Code Development Corporation.
**
** -#- -I- --Date-- ---------------------------------------Description----------------------------------------
** 001 GES 20090113 High level API for a provider of a specific network transport. This represents a logical 
**                  connection that is network independent and allows for a generic stream oriented use 
**                  pattern.
** 002 CA  20210827 Refactored to allow other test types, beside terminal (which can be executed from the same 
**                  test suite).  Added SOAP and REST web service tests.
*/

/*
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU Affero General Public License as
** published by the Free Software Foundation, either version 3 of the
** License, or (at your option) any later version.
**
** This program 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 Affero General Public License for more details.
**
** You should have received a copy of the GNU Affero General Public License
** along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

package com.goldencode.harness.transport;

import java.io.*;
import com.goldencode.harness.*;

/**
 * High level API for a provider of a specific network transport. This
 * represents a logical connection that is network independent and allows for
 * a generic stream oriented use pattern.
 */
public interface Connection
{
   /**
    * Connect to the defined system/account and initialize a working
    * communications session.
    *
    * @param    cfg
    *           Connection configuration.
    * @param    rc
    *           Object in which to store the details of failures.
    *
    * @return   <code>true</code> if the connection was successfully made
    *           and is now usable. <code>false</code> on any failure.
    */
   public boolean connect(TerminalSessionSettings cfg, FailureNotification rc);

   /**
    * Disconnect the currently working communications session.
    */
   public void disconnect();
   
   /**
    * Return the output destination for the currently working communications
    * session.
    *
    * @param    rc
    *           Object in which to store the details of failures.
    *
    * @return   The stream to be written to or <code>null</code> if the
    *           communications session is invalid or not active.
    */
   public OutputStream getOutputStream(FailureNotification rc);
   
   /**
    * Return the input source for the currently working communications
    * session.
    *
    * @param    rc
    *           Object in which to store the details of failures.
    *
    * @return   The stream to be read from or <code>null</code> if the
    *           communications session is invalid or not active.
    */
   public InputStream getInputStream(FailureNotification rc);
}
