/*
 *   
 *
 * Copyright  1990-2006 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation. 
 * 
 * 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
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt). 
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA 
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions. 
 */

package com.sun.tck.wma;

import java.io.IOException;

/** 
 * A connection handler for generic message sending and receiving.
 */ 

public interface MessageConnection {

    /**
     * Constant for a message type for <strong>text</strong> 
     * messages (value = "text").
     * If this constant is used for the <code>type</code> parameter in the 
     * <code>newMessage()</code> 
     * methods, then the newly created <code>Message</code>
     * will be an instance
     * implementing the <code>TextMessage</code> interface.
     */
    public static final String TEXT_MESSAGE = "text";

    /**
     * Constant for a message type for <strong>binary</strong>
     *  messages (value = "binary").
     * If this constant is used for the <code>type</code> parameter in the 
     * <code>newMessage()</code> 
     * methods, then the newly created <code>Message</code>
     *  will be an instance
     * implementing the <code>BinaryMessage</code> interface.
     */
    public static final String BINARY_MESSAGE = "binary";

    /**
     * Constant for a message type for <strong>multipart MIME</strong>
     *  messages (value = "multipart").
     * Using this constant as the <code>type</code> parameter in the
     * <code>newMessage()</code> methods will cause the newly created
     * <code>Message</code> to be an instance implementing the
     * <code>MultipartMessage</code> interface.
     * @since WMA 2.0
     */
    public static final String MULTIPART_MESSAGE = "multipart";


    /**
     * Constructs a new message object of a given type. When the 
     * string <code>text</code> is passed in, the created 
     * object implements the <code>TextMessage</code> interface.
     * When the <code>binary</code> constant is passed in, the 
     * created object implements the <code>BinaryMessage</code> 
     * interface. Adapter definitions for messaging protocols can define
     * new constants and new subinterfaces for the <code>Message</code>s.
     * The type strings are case-sensitive.
     *
     * <p>For adapter definitions that are not defined within the JCP 
     * process, the strings used <strong>must</strong> begin with 
     * an inverted domain 
     * name controlled by the defining organization, as is
     * used for Java package names. Strings that do not contain a 
     * full stop character "." are reserved for specifications done 
     * within the JCP process and <strong>must not</strong> be used by 
     * other organizations
     * defining adapter specification.
     * </p> 
     * <p>When this method is called from a <em>client</em> mode connection,
     * the newly created <code>Message</code> has the destination address
     * set to the address identified when this <code>Connection</code> 
     * was created.
     * </p>
     * <p>When this method is called from a <em>server</em> mode connection,
     * the newly created Message does not have the destination
     * address set. It must be set by the application before
     * trying to send the message.
     * </p>
     * @param type the type of message to be created. There are 
     *             constants for basic types defined in 
     *             this interface
     * @throws java.lang.IllegalArgumentException if the message
     *         type is not <code>TEXT_MESSAGE</code> or
     *         <code>BINARY_MESSAGE</code>
     * @return Message object for a given type of message
     */
    public Message newMessage(String type);   

    /** 
     * Constructs a new message object of a given type and
     * initializes it with the given destination address.
     * The semantics related to the parameter <code>type</code>
     * are the same as for the method signature with just the
     * <code>type</code> parameter.
     * 
     * @param type the type of message to be created. There are 
     *             constants for basic types defined in 
     *             this interface.
     * @param address destination address for the new message
     * @return <code>Message</code> object for a given type of message
     * @throws java.lang.IllegalArgumentException if the message
     *         type is not <code>TEXT_MESSAGE</code> or
     *         <code>BINARY_MESSAGE</code>
     * @see #newMessage(String type)
     */
    public Message newMessage(String type, String address);

    /**
     * Sends a message.
     * 
     * @param msg the message to be sent
     * @throws java.io.IOException if the message could not be sent
     *          or because of network failure
     * @throws java.lang.IllegalArgumentException if the message is
     *         incomplete or contains invalid information
     *         This exception
     *         is also thrown if the payload of the message exceeds 
     *         the maximum length for the given messaging protocol.
     * @throws java.io.InterruptedIOException if a timeout occurs while
     *         trying to send the message or if this <code>Connection</code> 
     *         object is closed during this send operation
     * @throws java.lang.NullPointerException if the parameter is null
     * @throws java.lang.SecurityException if the application does not 
     *         have permission to send the message
     * @see #receive()
     */
    public void send(Message msg) 
	throws java.io.IOException, java.io.InterruptedIOException;

    /** 
     * Receives a message.
     * 
     * <p>If there are no <code>Message</code>s for this 
     * <code>MessageConnection</code> waiting,
     * this method will block until a message for this <code>Connection</code>
     * is received, or the <code>MessageConnection</code> is closed.
     * </p>
     * @return a <code>Message</code> object representing the 
     *         information in the received message
     * @throws java.io.IOException if an error occurs while receiving
     *         a message
     * @throws java.io.InterruptedIOException if this 
     *         <code>MessageConnection</code> object
     *         is closed during this receive method call
     * @throws java.lang.SecurityException if the application does not 
     *         have permission to receive messages using the given port
     *         number
     * @see #send(Message)
     */
    public Message receive()
	throws java.io.IOException, java.io.InterruptedIOException;

    /** 
     * Close the connection.
     * When the connection has been closed access to all methods except this one
     * will cause an an IOException to be thrown. Closing an already closed
     * connection has no effect. Streams derived from the connection may be open
     * when method is called. Any open streams will cause the
     * connection to be held open until they themselves are closed.
     * @throws java.io.IOException - If an I/O error occurs
     */

    public void close() 
        throws IOException;
}



