messageelement.java

jxta_src_2.41b jxta 2.41b 最新版源码 from www.jxta.org

/*
 *
 * $Id: MessageElement.java,v 1.25 2005/08/08 19:59:05 bondolo 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.DataInput;
import java.io.DataInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.Reader;
import java.lang.ref.SoftReference;
import java.util.HashMap;
import java.util.Map;

import java.io.UnsupportedEncodingException;

import org.apache.log4j.Level;
import org.apache.log4j.Logger;

import net.jxta.document.Document;
import net.jxta.document.MimeMediaType;
import net.jxta.util.CountingOutputStream;
import net.jxta.util.DevNullOutputStream;

// imported for implementation of {@link #getUniqueName()} and {@link #getSequentialName()}
import net.jxta.impl.id.UUID.UUIDFactory;

/**
 * JXTA Message Elements are used to add data to a Message. Message Elements are
 * immutable objects. A Message Element may be shared amongst as many messages
 * as is desired. A Message Element is composed of four components:
 *
 *  <ul>
 *  <li>An optional name. This may be any {@link java.lang.String}. Unnamed
 * elements are assumed to have the name "" (the empty string).</li>
 *  <li>An optional {@link net.jxta.document.MimeMediaType}. If not specified
 * the Mime Media Type is assumed to be "Application/Octet-Stream".</li>
 *  <li>Data. Sub-classes of MessageElement allow you to create elements based
 * on a variety of data formats.</li>
 *  <li>An optional signature. This is a Message Element that is associated to
 *  this element and may contain a cryptographic signature/hash of this message
 *  element.
 *  </li>
 *
 *  <p/>The data contained with in a MessageElement is accessible in four ways:
 *
 *  <ul>
 *  <li>As an {@link java.io.InputStream}</li>
 *  <li>Sending the data a {@link java.io.OutputStream}</li>
 *  <li>As a {@link java.lang.String}.</li>
 *  <li>As a byte array.</li>
 *  </ul>
 *
 * @see net.jxta.endpoint.Message
 */
public abstract class MessageElement implements Document {
    
    /**
     *  Log4J logger
     **/
    private static transient final Logger LOG = Logger.getLogger( MessageElement.class.getName());
    
    /**
     *  The name of this element. May be the empty string ("") if the element is
     *  unnamed.
     **/
    protected final String name;
    
    /**
     *  The type of this element.
     **/
    protected final MimeMediaType type;
    
    /**
     *  The optional element which digitially signs or digests this element.
     *  If null then the element is has no signature element.
     **/
    protected final MessageElement sig;
    
    /**
     *  message properties hashmap
     **/
    protected Map properties = new HashMap();
    
    /**
     *  cached result of {@link #getByteLength()} operation.
     **/
    protected transient long cachedGetByteLength = -1;
    
    /**
     *  cached result of {@link #getBytes(boolean)} operation.
     **/
    protected transient SoftReference cachedGetBytes = null;
    
    /**
     *  cached result of {@link #toString()} operation.
     **/
    protected transient SoftReference cachedToString = null;
    
    /**
     * Returns a pseudo-random unique string which can be used as an element
     * name.
     *
     * @return String containing a pseudo-random value
     */
    public static String getUniqueName() {
        return UUIDFactory.newUUID().toString();
    }
    
    /**
     * Returns a string containing a pseudo-random unique string. The result of
     * <code>String.compare()</code> will be consistent with the order in which
     * results were returned from this function.
     *
     * <p/>Security Consideration : Be aware that the pseudo random portion of
     * the names generated by this string are shared amongst all peer groups
     * running in the same classloader. You may be at a risk for loss of
     * annonimity if you use the element names produced in more than one peer
     * group.
     *
     * @return String containing a pseudo-random value. The result of
     * <code>String.compare()</code> will be consistent with the order in
     * which results were returned from this function.
     *
     */
    public static String getSequentialName() {
        return UUIDFactory.newSeqUUID().toString();
    }
    
    /**
     *  Internal constructor for initializaing everything but the data.
     *
     *   @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 sig optional message digest/digital signature elemnent. If
     *    no signature is to be specified, pass null.
     **/
    protected MessageElement( String name, MimeMediaType type, MessageElement sig ) {
        this.name = ( null != name ) ? name : "";
        
        this.type = ( null != type ) ? type : MimeMediaType.AOS;
        
        if( (null != sig) && (null != sig.sig) ) {
            throw new IllegalArgumentException( "Invalid Signature Element. Signatures may not have signatures." );
        }
        
        this.sig = sig;
    }
    
    /**
     *  {@inheritDoc}
     *
     *  @deprecated Since Message Elements are immutable this method does
     *  nothing useful.
     **/
    public final Object clone( ) {
        return this;
    }
    
    /**
     *  {@inheritDoc}
     *
     *  <p/>Elements are considered equal if they have the same name, type and
     *  signatures. Element data is not considered by this implementation as
     *  it is mostly intended for subclass use.
     *
     **/
    public boolean equals( Object target ) {
        if( this == target ){
            return true;  // same object
        }
        
        if( target instanceof MessageElement ) {
            MessageElement likeMe = (MessageElement) target;
            
            // sig is nullable so test seperatly.
            boolean sigequals = (null != sig) ? sig.equals( likeMe.sig ) : (null==likeMe.sig);
            
            return sigequals &&
            name.equals( likeMe.name ) &&
            type.equals( likeMe.type );
        }
        
        return false; // not a MessageElement
    }
    
    /**
     *  {@inheritDoc}
     **/
    public int hashCode( ) {
        int sigHash = ( (null != getSignature()) && (this != getSignature())) ?
        getSignature().hashCode() : 1;
        
        int result =  sigHash * 2467 + // a prime
        getElementName().hashCode() * 3943 + // also a prime
        getMimeType().hashCode();
        
        return (0 != result) ? result : 1;
    }
    
    /**
     *  {@inheritDoc}
     *
     *  <p/>Returns a String representation of the element data. The
     *  <code>'charset'</code> parameter of the message element's mimetype, if
     *  any, is used to determine encoding. If the charset specified is
     *  unsupported then the default enconding will be used.
     *
     *  <p/>synchronized for caching purposes.
     **/
    public synchronized String toString( ) {
        String result = null;