endpointaddress.java

JXTA&#8482 is a set of open, generalized peer-to-peer (P2P) protocols that allow any networked devi

/*
 * Copyright (c) 2001-2007 Sun Microsystems, Inc.  All rights reserved.
 *  
 *  The Sun Project JXTA(TM) Software License
 *  
 *  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 Sun Microsystems, Inc. for JXTA(TM) technology." 
 *     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.
 *  
 *  JXTA is a registered trademark of Sun Microsystems, Inc. in the United 
 *  States and other countries.
 *  
 *  Please see the license information page at :
 *  <http://www.jxta.org/project/www/license.html> for instructions on use of 
 *  the license in source files.
 *  
 *  ====================================================================
 *  
 *  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 net.jxta.id.ID;
import net.jxta.logging.Logging;

import java.lang.ref.SoftReference;
import java.net.URI;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * Describes a destination to which JXTA messages may be sent. This may be:
 * <p/>
 *
 *  <ul>
 *      <li>A Pipe</li>
 *      <li>A Peergroup (propagate)</li>
 *      <li>A Peer</li>
 *      <li>A Message Transport for a Peer</li>
 *  </ul>
 *<p/>
 *  An Endpoint Address is a specialized interpretation of a URI.
 *  Wherever it makes sense you should use a URI in preference to an Endpoint
 *  Address. An Endpoint Address is composed of four components: a protocol
 *  (also called a scheme), a protocol address (also called an authority), an
 *  optional service name and optional service parameter.
 *<p/>
 *  <b>The Protocol</b><ul>
 *      <li>Describes the method of addressing used by the remainder of the
 *      endpoint address.</li>
 *      <li>Indicates how the address will be resolved, ie. who will resolve it.</li>
 *      <li>Corresponds to the "scheme" portion of a URI in W3C parlance.
 *      <li><b>May not</b> contain the ":" character.
 *  </ul>
 *<p/>
 *  <b>The Protocol Address</b><ul>
 *      <li>Describes the destination entity of this address.</li>
 *      <li>Form is dependant upon the protocol being used.</li>
 *      <li>Corresponds to the "Authority" portion of a URI in W3C parlance.
 *      <li><b>May not</b> contain the "/" character.
 *  </ul>
 *<p/>
 *  <b>The Service Name</b> (optional)<ul>
 *      <li>Describes the service that is the destination. A service cannot be
 *      a protocol address because a service must have a location; a group or a
 *      specific peer.</li>
 *      <li>Form is dependant upon service intent. This is matched as a UTF8
 *      string.</li>
 *      <li><b>May not</b> contain the "/" character.
 *  </ul>
 *
 *  <p/><b>The Service Parameter</b> (optional)<ul>
 *      <li>Describes parameters for the service.</li>
 *      <li>Form is dependant upon service intent. This is matched as a UTF-8
 *      string (if it is used for matching).</li>
 *  </ul>
 *
 * @see net.jxta.endpoint.EndpointService
 * @see net.jxta.endpoint.MessageTransport
 * @see net.jxta.endpoint.Messenger
 * @see net.jxta.pipe.PipeService
 */
public class EndpointAddress {

    /**
     * Logger
     */
    private static final Logger LOG = Logger.getLogger(EndpointAddress.class.getName());

    /**
     * If {@code true} then endpoint addresses based upon IDs are represented
     * using the "jxta://" form. If false then they are presented using the
     * "urn:jxta:" form. The two forms are meant to be logically equivalent.
     */
    private final static boolean IDS_USE_JXTA_URL_FORM = true;

    /**
     * The default protocol value for Endpoint Addresses based upon JXTA IDs.
     */
    private final static String JXTA_ID_PROTOCOL = ID.URIEncodingName + ":" + ID.URNNamespace;

    /**
     * if true then the address is a url, otherwise its a uri (likely a urn).
     */
    private boolean hierarchical = true;

    /**
     * Describes the method of addressing used by the remainder of the
     * endpoint address.
     */
    private String protocol = null;

    /**
     * Describes the destination entity of this address.
     */
    private String protocolAddress = null;

    /**
     * Describes the service that is the destination.
     */
    private String service = null;

    /**
     * Describes parameters for the service.
     */
    private String serviceParam = null;

    /**
     * cached calculated hash code.
     */
    private transient int cachedHashCode = 0;

    /**
     * cached copy of string representation.
     */
    private transient SoftReference<String> cachedToString = null;

    /**
     * Returns an unmodifiable clone of the provided EndpointAddress.
     *
     * @param address the address to be cloned.
     * @return the unmodifiable address clone.
     * @deprecated All EndpointAddresses are now unmodifiable so this method is
     *             no longer needed.
     */
    @Deprecated
    public static EndpointAddress unmodifiableEndpointAddress(EndpointAddress address) {
        return address;
    }

    /**
     * Builds an Address from a string
     *
     * @param address the string representation of the address.
     */
    public EndpointAddress(String address) {
        parseURI(address);
    }

    /**
     * Create an EndpointAddress whose value is initialized from the provided
     * URI.
     *
     * @param address the URI representation of the address.
     */
    public EndpointAddress(URI address) {
        this(address.toString());
    }

    /**
     * Constructor which builds an endpoint address from a base address and
     * replacement service and params
     *
     * @param base         The EndpointAddress on which the new EndpointAddress will be based
     * @param service      The service name for the endpoint address or
     *                     {@code null} if there is no service name.
     * @param serviceParam The service parameter for the endpoint address or
     *                     {@code null} if there is no parameter.
     */
    public EndpointAddress(EndpointAddress base, String service, String serviceParam) {
        setProtocolName(base.getProtocolName());
        setProtocolAddress(base.getProtocolAddress());
        setServiceName(service);
        setServiceParameter(serviceParam);
    }

    /**
     * Constructor which builds an address the four standard constituent parts.
     *
     * @param protocol     The addressing scheme to be used for the endpoint address.
     * @param address      The destination for the endpoint address.
     * @param service      The service name for the endpoint address or
     *                     {@code null} if there is no service name.
     * @param serviceParam The service parameter for the endpoint address or
     *                     {@code null} if there is no parameter.
     */
    public EndpointAddress(String protocol, String address, String service, String serviceParam) {
        setProtocolName(protocol);
        setProtocolAddress(address);
        setServiceName(service);
        setServiceParameter(serviceParam);
    }

    /**
     * Constructor which builds an address from a standard jxta id and a
     * service and param.
     *
     * @param id           the ID which will be the destination of the endpoint address.
     * @param service      The service name for the endpoint address or
     *                     {@code null} if there is no service name.
     * @param serviceParam The service parameter for the endpoint address or
     *                     {@code null} if there is no parameter.
     */
    public EndpointAddress(ID id, String service, String serviceParam) {
        setProtocolName(JXTA_ID_PROTOCOL);
        setProtocolAddress(id.getUniqueValue().toString());
        setServiceName(service);
        setServiceParameter(serviceParam);
    }

    /**
     * {@inheritDoc}
     *
     * @deprecated EndpointAddress objects are immutable and never need to be
     *             cloned.
     */
    @Override
    @Deprecated
    public EndpointAddress clone() {
        return this;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public boolean equals(Object target) {
        if (this == target) {
            return true;
        }

        if (target instanceof EndpointAddress) {
            EndpointAddress likeMe = (EndpointAddress) target;

            boolean result = (hierarchical == likeMe.hierarchical) && protocol.equalsIgnoreCase(likeMe.protocol)
                    && protocolAddress.equalsIgnoreCase(likeMe.protocolAddress)
                    && ((service != null)
                    ? ((likeMe.service != null) && service.equals(likeMe.service))
                    : (likeMe.service == null))
                    && ((serviceParam != null)
                    ? ((likeMe.serviceParam != null) && serviceParam.equals(likeMe.serviceParam))
                    : (likeMe.serviceParam == null));

            return result;
        }

        return false;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public int hashCode() {
        if (0 == cachedHashCode) {
            int calcedHashCode = protocol.toLowerCase().hashCode();

            calcedHashCode += protocolAddress.hashCode() * 5741; // a prime
            calcedHashCode += ((service != null) ? service.hashCode() : 1) * 7177; // a prime
            calcedHashCode += ((serviceParam != null) ? serviceParam.hashCode() : 1) * 6733; // a prime

            cachedHashCode = (0 == calcedHashCode) ? 1 : calcedHashCode;
        }

        return cachedHashCode;
    }

    /**
     * {@inheritDoc}
     */
    @Override
    public synchronized String toString() {
        String result;