message.java

jxme的一些相关程序,主要是手机上程序开发以及手机和计算机通信的一些程序资料,程序编译需要Ant支持

/************************************************************************
 *
 * $Id: Message.java,v 1.2 2002/03/04 20:18:38 echtcherbina Exp $
 *
 * Copyright (c) 2001 Sun Microsystems, Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:
 *       "This product includes software developed by the
 *       Sun Microsystems, Inc. for Project JXTA."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA"
 *    must not be used to endorse or promote products derived from this
 *    software without prior written permission. For written
 *    permission, please contact Project JXTA at http://www.jxta.org.
 *
 * 5. Products derived from this software may not be called "JXTA",
 *    nor may "JXTA" appear in their name, without prior written
 *    permission of Sun.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL SUN MICROSYSTEMS  OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of Project JXTA.  For more
 * information on Project JXTA, please see
 * <http://www.jxta.org/>.
 *
 * This license is based on the BSD license adopted by the Apache Foundation.
 *********************************************************************************/

package net.jxta.endpoint;

import java.io.InputStream;
import java.io.IOException;
import java.util.Enumeration;
import net.jxta.document.MimeMediaType;
import net.jxta.util.StringEnumeration;


/** 
 * Message defines the interface of messages sent or received to or
 * from an endpoint and pipes.  Applications are expected to implement this
 * interface in order to exchange messages.
 * <P>
 * A Message is an object that can be sent or received using the EndpointService
 * API or the PipeService API.
 * <p>
 * A message contains a set MessageElements.
 *
 * @see  net.jxta.endpoint.MessageElement
 * @see  net.jxta.endpoint.EndpointAddress
 * @see  net.jxta.endpoint.EndpointService
 * @see  net.jxta.pipe.InputPipe
 * @see  net.jxta.pipe.OutputPipe
 * @see  net.jxta.pipe.PipeService
 */

public interface Message {
    
    /**
     *   Create a new MessageElement
     * <p>
     *   @param name Name of the Element. May be the empty string ("") if
     *    the Element is not named.
     *   @param type Type of the Element. null is equivalent to specifying
     *    the type "Application/Octet-stream"
     *   @param in the stream containing the body of the Element. The stream 
     *    will be closed by the Element.
     *   @return MessageElement new Message Element.
     *   @throws NullPointerException if name or InputStream are null.
     *
     **/
    public MessageElement newMessageElement(String name,
					    MimeMediaType type, 
					    InputStream in) throws IOException;    
    
    /**
     *   Create a new Element, but dont add it to the message.
     *
     *   @param name Name of the Element. May be the empty string ("") if
     *    the Element is not named.
     *   @param type Type of the Element. null is equivalent to specifying
     *    the type "Application/Octet-stream"
     *   @param in the stream containing the body of the Element. If the
     *    stream does not support the "mark" operation then a copy of the
     *    stream contents is made immediately. The stream will <b>NOT</b> be
     *    closed by the Element.
     *   @param len The size of the Element will be limited to len bytes
     *    from the stream. If you are using the stream interface and know
     *    the size of the stream, specifying it here improves performance
     *    and space effciency a lot.
     *   @return MessageElement new Message Element.
     *   @throws NullPointerException if name or InputStream are null.
     *
     *  @since JXTA 1.0
     **/
    public MessageElement newMessageElement(String name,
					    MimeMediaType type, 
					    InputStream in,
					    int len) throws IOException;
    
    /**
     * Create a new Element, but dont add it to the message. The contents
     * of the byte array are not copied.
     *
     * @param name Name of the Element. May be the empty string ("") if
     *   the Element is not named.
     * @param type Type of the Element. null is equivalent to specifying
     *   the type "Application/Octet-stream"
     * @param b A byte array containing the contents of this element.
     * @param offset all bytes before this location in <code>b</code>
     *   will be ignored.
     *
     *   @return MessageElement new Message Element.
     * @throws NullPointerException if name or b are null.
     * @throws IndexOutOfBoundsException if offset is negative or greater
     *  than or equal to the length of <code>b</code>
     *
     * @since JXTA 1.0
     */
    public MessageElement newMessageElement(String name, 
					    MimeMediaType type, 
					    byte[] b,
					    int offset,
					    int len);

    /**
     *  Create a new Element, but dont add it to the message. The contents
     *  of the byte array are not copied.
     *
     *  @param name Name of the Element. May be null if
     *    the Element is not named.
     *  @param type Type of the Element. null is equivalent to specifying
     *    the type "Application/Octet-stream"
     *  @param b A byte array containing the contents of this element.
     *  @param offset all bytes before this location in <code>b</code>
     *    will be ignored.
     *
     *   @return MessageElement new Message Element.
     *  @throws NullPointerException if name or b are null.
     *  @throws IndexOutOfBoundsException if offset is negative or greater
     *   than or equal to the length of <code>b</code>
     *
     *  @since JXTA 1.0
     **/
    public MessageElement newMessageElement(String name,
					    MimeMediaType type, 
					    byte[] b);
        
    /**
     *  Add a MessageElement into the message. 
     * <p>
     *  @param add the Element to add to the message.
     *
     *  @since JXTA 1.0
     **/
    public void addElement( MessageElement add );

    /**
     * Chck for a message element with the given name.
     * <p>
     * @param nsname name of the message element to search for.
     * @return boolean true if the element is present, flase otherwise.
     */
    public boolean hasElement(String nsname);

    /**
     *  Retrieve a element by name from the message
     *
     * @param nsname name of the message element to search for.
     *  @return MessageElement the element.
     *
     *  @since JXTA 1.0
     **/
    public MessageElement getElement( String name );
        
    /**
     *  Returns an enumeration of all of the elements contained in this message. 
     *  Elements from all namespaces are returned.
     *<P>
     *  The Enumeration returned is not synchronized with the message. If you
     *  modify the state of the Message, the enumeration will not reflect your
     *  changes.
     * <P>
     * Same as getElementsInLifoOrder().
     *
     *  @return Enumeration of Elements.
     *
     * @since JXTA 1.0
     **/
    public MessageElementEnumeration getElements();
    
    /**
     * Return a StringEnumeration for all the message
     * element names in this message.
     * <p>
     * @return StringEnumeration StringEnumeration of the names of the Message Element contained
     * the message.
     */
    public StringEnumeration getNames();
    
    /**
     *  Remove an element from a message.
     * <p>
     *  @param remove the Element to remove from the message.
     *  @return boolean returns true if the element was removed, otherwise false.
     *
     * @since JXTA 1.0
     **/
    public boolean removeElement( MessageElement remove );
    

    /**
     *  Remove an element from a message by its name.
     * <p>
     *  @param name name of the Element to remove from the message.
     *  @return MessageElement removed Message Element, or null if there was no
     * MessageElement to removed.
     *
     * @since JXTA 1.0
     **/
    public MessageElement removeElement( String name);


    /**
     * Create or replace a MessageElement using the given namespace and name.  The
     * contents of the element is given by the byte array passed in.
     */
    public void setBytes(String name, byte[] bytes);

    /**
     * Create or replace an element and add it to the message.  The namespace
     * and name of the element are as defined by the arguments of 
     * the same name.  The value of the element is set form the
     * InputStream.
     *
     * @param name Name of the new element.
     * @param bytes byte array which defines the value of the element.
     * @param offset Start location in byte array.
     * @param len Length of byte array segment startin at offset.
     */
    public void setBytes(String name,
			 byte[] bytes,
			 int offset,
			 int len);

    /**
     * get the named element from the message and return
     * the element's byte array.  
     * <P>
     * Note that the element is not removed from the message
     * post: offset == 0. len == bytes.length.  
     * <p>
     * @param qname name of the element to get.
     * @return byte[] the element byte array.
     */
    public byte[] getBytes(String qname);
    

    /**
     * Return an Enumeration of all namespace names used in this message.
     * <p>
     * @return Enumeration of all namespaces used in this message.
     */
    public Enumeration getNamespaces();
    
    /**
     * Deep copy of message.
     * <p>
     * @return Object a Message that is a copy of the original message
     *
     * @since JXTA 1.0
     **/
     public Object clone();
     
    /**
     * Check if two message are equals
     * <p>
     * @param o is a Message object to compare with.
     * <p>
     * @return boolean returns true if both messages are equal, otherwise returns false.
     **/
     public boolean equals(Object o);
    
     /**
      * Get the source address from the message. The element 
      * is named "jxta:EndpointSourceAddress".  If the element
      * is not present return null.
      * <P>
      * Convenience method.
      * <p>
      * @rturn EndpointAddress esource address, or null if not present.
      */
    public EndpointAddress getSourceAddress();

     /**
      * Get the desitnation address from the message. The element 
      * is named "jxta:EndpointDestinationAddress".  If 
      * the element is not present return null.
      * <P>
      * Convenience method.
      * <p>
      * @return EndpointAddress destination address, or null if not present.
      */
    public EndpointAddress getDestinationAddress();    

    /**
      * Set the source address on to the message. The element 
      * is named ""jxta:EndpointSourceAddress". 
      * <P>
      * Convenience method.
      * @param srcAddress EndpointAddress of the source of the message.
      */    
    public void setSourceAddress(EndpointAddress srcAddress);    
    
    /**
      * Set the destination address on to the message. The element 
      * is named "jxta:EndpointDestinationAddress". 
      * <P>
      * Convenience method.
      * @param dstAddress EndpointAddress of the destination of the message.
      */    
    public void setDestinationAddress(EndpointAddress dstAddress);

    /**
     * Set the string on to the message.  
     * <P>
     * Convenience method.
     * <p>
     * @param  elementName name of the element that will contain the String
     * @param s content of the Message Element.
     */
    public void setString(String elementName, String s);
    
    /**
     * Get the element from the message as a string.
     * @return the string, or null if the element is
     *         not present.
     * <P>
     * Convenience method.
     * @return String the string, or null if the element is
     *         not present.
     **/
    public String getString(String elementName);

}