001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.tck.wma;
028:
029: import java.io.IOException;
030:
031: /**
032: * A connection handler for generic message receiving and sending.
033: */
034: public interface MessageConnection {
035:
036: /**
037: * Constant designating a message type for <strong>text</strong>
038: * messages, i.e. value = "text".
039: * When this constant is used for the <code>newMessage()</code> methods
040: * <code>type</code> parameter, the new <code>Message</code> object
041: * will implement the <code>TextMessage</code> interface.
042: */
043: public static final String TEXT_MESSAGE = "text";
044:
045: /**
046: * Constant designating a message type for <strong>binary</strong>
047: * messages, i.e. value = "binary".
048: * When this constant is used for the <code>newMessage()</code> methods
049: * <code>type</code> parameter, the new <code>Message</code> object
050: * will implement the <code>BinaryMessage</code> interface.
051: */
052: public static final String BINARY_MESSAGE = "binary";
053:
054: /**
055: * Constant designating a message type for <strong>multipart MIME</strong>
056: * messages, i.e. value = "multipart".
057: * When this constant is used for the <code>newMessage()</code> methods
058: * <code>type</code> parameter, the new <code>Message</code> object
059: * will implement the <code>MultipartMessage</code> interface.
060: * @since WMA 2.0
061: */
062: public static final String MULTIPART_MESSAGE = "multipart";
063:
064: /**
065: * Constructs a new message object of a specified type.
066: *
067: * @param type the type of message to create.
068: * @throws java.lang.IllegalArgumentException if the message
069: * type isn't <code>BINARY_MESSAGE</code> or
070: * <code>TEXT_MESSAGE</code>
071: * @return a newly constructed message object of a given type
072: */
073: public Message newMessage(String type);
074:
075: /**
076: * Constructs a new message object of a specified type
077: * initialized with the specified destination address.
078: *
079: * @param type the type of message to create.
080: * @param address the new message's destination address
081: * @return a newly constructed message object of a given type
082: * @throws java.lang.IllegalArgumentException if the message
083: * type isn't <code>BINARY_MESSAGE</code> or
084: * <code>TEXT_MESSAGE</code>
085: * @see #newMessage(String type)
086: */
087: public Message newMessage(String type, String address);
088:
089: /**
090: * Sends a message.
091: *
092: * @param msg the message to be sent
093: * @throws java.io.IOException network failure has occured, or the message
094: * couldn't be sent due to other reasons
095: * @throws java.lang.IllegalArgumentException if the message contains
096: * invalid information or is incomplete, or the payload
097: * exceeds the maximal length allowed by the given messaging
098: * protocol.
099: * @throws java.io.InterruptedIOException if the connection is closed during
100: * the send operation, or if a timeout occurs while sending
101: * the message
102: * @throws java.lang.NullPointerException if <code>msg</code> is null
103: * @throws java.lang.SecurityException if the application doesn't
104: * have permission for sending the message
105: * @see #receive()
106: */
107: public void send(Message msg) throws java.io.IOException,
108: java.io.InterruptedIOException;
109:
110: /**
111: * Receives a message.
112: *
113: * <p>If there are no <code>Message</code>s for this
114: * <code>MessageConnection</code> waiting,
115: * this method will block until a message for this <code>Connection</code>
116: * is received, or the <code>MessageConnection</code> is closed.
117: * </p>
118: * @return a received message represented by the <code>Message</code> object
119: * @throws java.io.IOException if an error occurs while receiving
120: * a message
121: * @throws java.io.InterruptedIOException if the connection is closed during
122: * the receive operation
123: * @throws java.lang.SecurityException if the application doesn't
124: * have permission for receiving messages on the given port
125: * @see #send(Message)
126: */
127: public Message receive() throws java.io.IOException,
128: java.io.InterruptedIOException;
129:
130: /**
131: * Close the connection.
132: * @throws java.io.IOException if an I/O error occurs
133: */
134: public void close() throws IOException;
135: }
|