/*****************************************************************
JADE - Java Agent DEvelopment Framework is a framework to develop 
multi-agent systems in compliance with the FIPA specifications.
Copyright (C) 2000 CSELT S.p.A. 

The updating of this file to JADE 2.0 has been partially supported by the IST-1999-10211 LEAP Project

GNU Lesser General Public License

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, 
version 2.1 of the License. 

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.
*****************************************************************/

package jade.mtp;

import jade.domain.FIPAAgentManagement.Envelope;

/**
   Abstract interface for Message Transport Protocols

   @author Giovanni Rimassa - Universita` di Parma
   @version $Date$ $Revision$

*/
public interface MTP {

  /**
     Callback interface to be notified of message arrivals over this
     Message Transport Protocol.
   */
  public static interface Dispatcher {
    void dispatchMessage(Envelope env, byte[] payload);
  }

  /**
     Generic exception class for MTP errors.
   */
  public static class MTPException extends Exception {

    /**
       @serial
    */
    private Throwable nested;

    /**
       Constructor for exception class.
       @param msg A message detailing the cause of the exception.
     */
    public MTPException(String msg) {
      this(msg, null);
    }

    /**
       Constructor for exception class.
       @param msg A message detailing the cause of the exception.
       @param t The exception wrapped by this object.
     */
    public MTPException(String msg, Throwable t) {
      super(msg);
      nested = t;
    }

    /**
      Reads the exception wrapped by this object.
      @return the <code>Throwable</code> object that is the exception thrown by
      the concrete MTP subsystem.
    */
    public Throwable getNested() {
      return nested;
    }

  } // End of MTPException class.


  /**
     Activates an MTP handler for incoming messages on a default
     address.
     @return A <code>TransportAddress</code>, corresponding to the
     chosen default address.
     @exception MTPException Thrown if some MTP initialization error
     occurs.
  */
  TransportAddress activate(Dispatcher disp) throws MTPException;

  /**
     Activates an MTP handler for incoming messages on a specific
     address.
     @param ta A <code>TransportAddress</code> object, representing
     the transport address to listen to.
     @exception MTPException Thrown if some MTP initialization error
     occurs.
   */
  void activate(Dispatcher disp, TransportAddress ta) throws MTPException;

  /**
     Deactivates the MTP handler listening at a given transport
     address.
     @param ta The <code>TransportAddress</code> object the handle to
     close is listening to.
     @exception MTPException Thrown if some MTP cleanup error occurs.
   */
  void deactivate(TransportAddress ta) throws MTPException;

  /**
     Deactivates all the MTP handlers.
     @exception MTPException Thrown if some MTP cleanup error occurs.
   */
  void deactivate() throws MTPException;

  /**
     Delivers to the specified address an ACL message, encoded in some
     concrete message representation, using the given envelope as a
     transmission header.
     @param ta The transport address to deliver the message to. It
     must be a valid address for this MTP.
     @param env The message envelope, containing various fields
     related to message recipients, encoding, and timestamping.
     @payload The byte sequence that contains the encoded ACL message.
     @exception MTPException Thrown if some MTP delivery error occurs.
   */
  void deliver(TransportAddress ta, Envelope env, byte[] payload) throws MTPException;

  /**
     Converts a string representing a valid address in this MTP to a
     <code>TransportAddress</code> object.
     @param rep The string representation of the address.
     @return A <code>TransportAddress</code> object, created from the
     given string.
     @exception MTPException If the given string is not a valid
     address according to this MTP.
   */
  TransportAddress strToAddr(String rep) throws MTPException;

  /**
     Converts a <code>TransportAddress</code> object into a string
     representation.
     @param ta The <code>TransportAddress</code> object.
     @return A string representing the given address.
     @exception MTPException If the given
     <code>TransportAddress</code> is not a valid address for this
     MTP.
   */
  String addrToStr(TransportAddress ta) throws MTPException;

  /**
     Reads the name of the message transport protocol managed by this
     MTP. The FIPA standard message transport protocols have a name
     starting with <code><b>"fipa.mts.mtp"</b></code>.
     @return A string, that is the name of this MTP.
   */
  String getName();

}

@@ -1111,58 +1111,8 @@
 p;%0A%0A
-import jade.domain.FIPAAgentManagement.Envelope;%0A%0A
 /**%0A
@@ -1276,2956 +1276,39 @@
 MTP 
-%7B%0A%0A  /**%0A     Callback interface to be notified of message arrivals over this%0A     Message Transport Protocol.%0A   */%0A  public static interface Dispatcher %7B%0A    void dispatchMessage(Envelope env, byte%5B%5D payload);%0A  %7D%0A%0A  /**%0A     Generic exception class for MTP errors.%0A   */%0A  public static class MTPException extends Exception %7B%0A%0A    /**%0A       @serial%0A    */%0A    private Throwable nested;%0A%0A    /**%0A       Constructor for exception class.%0A       @param msg A message detailing the cause of the exception.%0A     */%0A    public MTPException(String msg) %7B%0A      this(msg, null);%0A    %7D%0A%0A    /**%0A       Constructor for exception class.%0A       @param msg A message detailing the cause of the exception.%0A       @param t The exception wrapped by this object.%0A     */%0A    public MTPException(String msg, Throwable t) %7B%0A      super(msg);%0A      nested = t;%0A    %7D%0A%0A    /**%0A      Reads the exception wrapped by this object.%0A      @return the %3Ccode%3EThrowable%3C/code%3E object that is the exception thrown by%0A      the concrete MTP subsystem.%0A    */%0A    public Throwable getNested() %7B%0A      return nested;%0A    %7D%0A%0A  %7D // End of MTPException class.%0A%0A%0A  /**%0A     Activates an MTP handler for incoming messages on a default%0A     address.%0A     @return A %3Ccode%3ETransportAddress%3C/code%3E, corresponding to the%0A     chosen default address.%0A     @exception MTPException Thrown if some MTP initialization error%0A     occurs.%0A  */%0A  TransportAddress activate(Dispatcher disp) throws MTPException;%0A%0A  /**%0A     Activates an MTP handler for incoming messages on a specific%0A     address.%0A     @param ta A %3Ccode%3ETransportAddress%3C/code%3E object, representing%0A     the transport address to listen to.%0A     @exception MTPException Thrown if some MTP initialization error%0A     occurs.%0A   */%0A  void activate(Dispatcher disp, TransportAddress ta) throws MTPException;%0A%0A  /**%0A     Deactivates the MTP handler listening at a given transport%0A     address.%0A     @param ta The %3Ccode%3ETransportAddress%3C/code%3E object the handle to%0A     close is listening to.%0A     @exception MTPException Thrown if some MTP cleanup error occurs.%0A   */%0A  void deactivate(TransportAddress ta) throws MTPException;%0A%0A  /**%0A     Deactivates all the MTP handlers.%0A     @exception MTPException Thrown if some MTP cleanup error occurs.%0A   */%0A  void deactivate() throws MTPException;%0A%0A  /**%0A     Delivers to the specified address an ACL message, encoded in some%0A     concrete message representation, using the given envelope as a%0A     transmission header.%0A     @param ta The transport address to deliver the message to. It%0A     must be a valid address for this MTP.%0A     @param env The message envelope, containing various fields%0A     related to message recipients, encoding, and timestamping.%0A     @payload The byte sequence that contains the encoded ACL message.%0A     @exception MTPException Thrown if some MTP delivery error occurs.%0A   */%0A  void deliver(TransportAddress ta, Envelope env, byte%5B%5D payload) throws MTPException;
+extends InChannel, OutChannel %7B
 %0A%0A  

Split the interface in a hierarchy, to separate the management of outgoing and incoming messages.