idfactory.java

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

/*
 * 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.
 *
 * $Id: IDFactory.java,v 1.40 2005/12/08 17:21:06 bondolo Exp $
 */

package net.jxta.id;

import java.io.InputStream;
import java.lang.reflect.Field;
import java.net.URI;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;
import java.util.ResourceBundle;

import java.io.IOException;
import java.net.MalformedURLException;
import java.net.URISyntaxException;
import java.net.UnknownServiceException;
import java.util.MissingResourceException;
import java.util.NoSuchElementException;

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

import net.jxta.codat.CodatID;
import net.jxta.id.jxta.IDFormat;
import net.jxta.peer.PeerID;
import net.jxta.peergroup.PeerGroupID;
import net.jxta.pipe.PipeID;
import net.jxta.platform.ModuleClassID;
import net.jxta.platform.ModuleSpecID;
import net.jxta.util.ClassFactory;

/**
 *  A factory class for creating new ID instances and for constructing ID
 *  instances from external representations such as strings or URIs.
 *
 *  <p/>When possible the factory will create IDs of the same ID Format as any
 *  base ids provided. For example, PipeIDs will be created to be the same ID
 *  Format as the PeerGroupID provided.
 *
 *  <p/>Some ID constructors allow specification of "seed" information. Each ID
 *  Format may use this seed information as it chooses or may require seed
 *  information of a specific form. In some cases the seed information will be
 *  used literally as provided to construct the resulting ID, but ID Formats
 *  may also choose to ignore the seed information entirely, use it as random
 *  number generator seed values, etc. Consult the implementation documentation
 *  for the ID Formats of interest to see how the seed information is used by
 *  each ID Format.
 *
 *  @see net.jxta.id.ID
 *  @see net.jxta.util.ClassFactory
 *  @see <a href="http://spec.jxta.org/nonav/v1.0/docbook/JXTAProtocols.html#ids" target='_blank'>JXTA Protocols Specification : IDs</a>
 **/
public final class IDFactory extends ClassFactory {
    
    /**
     *  Interface for instantiators of IDs. Each ID Format registered with the
     *  ID Factory implements a class with this interface.
     **/
    public interface Instantiator {
        
        /**
         *  Returns the ID Format value associated with this ID Format
         *
         *  @return String containing the ID format value for this format.
         **/
        public String getSupportedIDFormat();
        
        /**
         *  Construct a new ID instance from a JXTA ID contained in a URL.
         *
         *  @deprecated Convert to fromURI.
         *
         *  @param source  URL which will be decoded to create a new ID instance.
         *  @return  ID containing the new ID instance initialized from the URL.
         *  @throws UnknownServiceException Is thrown if the URL provided is of
         *  a format unrecognized by this JXTA implementation.
         *  @throws MalformedURLException Is thrown if the URL provided is not
         *  a valid, recognized JXTA URL.
         **/
        public ID fromURL( URL source ) throws MalformedURLException, UnknownServiceException;
        
        /**
         *  Creates a new CodatID Instance. A new random CodatID is created for
         *  the provided Peer Group. This type of CodatID can be used as a
         *  canonical reference for dynamic content.
         *
         *  @see net.jxta.codat.Codat
         *
         *  @param groupID The group to which this content will belong.
         *  @return The newly created CodatID.
         **/
        public CodatID newCodatID( PeerGroupID groupID );
        
        /**
         *  Creates a new CodatID instance. A new CodatID is created for the
         *  provided Peer Group. This type of CodatID can be used as a
         *  canonical reference for dynamic content.
         *
         *  <p/>This varient of CodatID allows you to create "Well-known" codats
         *  within the context of diverse groups. This can be useful for common
         *  services that need to do discovery without advertisements or for
         *  network organization services.  Because of the potential for ID
         *  collisions and the difficulties with maintaining common service
         *  interfaces this varient of CodatID should be used with great caution
         *  and pre-planning.
         *
         *  @see net.jxta.codat.Codat
         *
         *  @param groupID The group to which this content will belong.
         *  @param seed The seed information which will be used in creating the
         *  codatID. The seed information should be at least four bytes in
         *  length, though longer values are better.
         *  @return The newly created CodatID.
         **/
        public CodatID newCodatID( PeerGroupID groupID, byte [] seed );
        
        /**
         *  Creates a new CodatID instance. A new random CodatID is created for
         *  the provided Peer Group and contains a hash value for the Codat data.
         *  This type of Codat ID is most appropriate for static content. By
         *  including a hash value this form of Codat ID provides greater
         *  assurance of the canonical property of IDs. It also allows the
         *  document content returned when this ID is used to be verified to
         *  ensure it has not been altered.
         *
         *  @see net.jxta.codat.Codat
         *
         *  @param groupID The group to which this ID will belong.
         *  @param in The InputStream from which the content hash is calculated.
         *  The stream is read until EOF and then closed.
         *  @return The newly created CodatID.
         *  @throws IOException I/O Error reading document
         **/
        public CodatID newCodatID(PeerGroupID groupID, InputStream in) throws IOException;
        
        /**
         *  Creates a new CodatID instance. A new CodatID is created for the
         *  provided Peer Group and contains a hash value for the Codat data.
         *  By including a hash value this form of Codat ID provides greater
         *  assurance of the canonical property of IDs. It also allows the
         *  document content returned when this ID is used to be verified to
         *  ensure it has not been altered. This type of Codat ID is most
         *  appropriate for static content.
         *
         *  <p/>This varient of CodatID allows you to create "Well-known" codats
         *  within the context of diverse groups. This can be useful for common
         *  services that need to do discovery without advertisements or for
         *  network organization services.  Because of the potential for ID
         *  collisions and the difficulties with maintaining common service
         *  interfaces this varient of CodatID should be used with great caution
         *  and pre-planning.
         *
         *  @see net.jxta.codat.Codat
         *
         *  @param groupID The group to which this ID will belong.
         *  @param seed The seed information which will be used in creating the
         *  codat ID. The seed information should be at least four bytes in
         *  length, though longer values are better.
         *  @param in The InputStream from which the content hash is calculated.
         *  The stream is read until EOF and then closed.
         *  @return The newly created CodatID.
         *  @throws IOException I/O Error reading document
         **/
        public CodatID newCodatID(PeerGroupID groupID, byte [] seed, InputStream in ) throws IOException;
        
        /**
         *  Creates a new PeerID instance. A new random peer id will be generated.
         *  The PeerID will be a member of the provided group.
         *
         *  @see net.jxta.peergroup.PeerGroup
         *
         *  @param groupID    the group to which this PeerID will belong.
         *  @return The newly created PeerID.
         **/
        public PeerID newPeerID(PeerGroupID groupID);
        
        /**
         *  Creates a new PeerID instance. A new PeerID will be generated.
         *  The PeerID will be a member of the provided group.
         *
         *  @see net.jxta.peergroup.PeerGroup
         *
         *  @param groupID    the group to which this PeerID will belong.
         *  @param seed   The seed information which will be used in creating the
         *  PeerID. The seed information should be at least four bytes in length,
         *  though longer values are better.
         *  @return The newly created PeerID.
         **/
        public PeerID newPeerID(PeerGroupID groupID, byte [] seed );
        
        /**
         *  Creates a new PeerGroupID instance. A new random peer group id will be
         *  generated. The PeerGroupID will be created using the default ID Format.
         *
         *  @see net.jxta.peergroup.PeerGroup
         *
         *  @return The newly created PeerGroupID.
         **/
        public PeerGroupID newPeerGroupID( );
        
        /**
         *  Creates a new PeerGroupID instance. A new PeerGroupID will be
         *  generated using the provided seed information. The PeerGroupID will
         *  be created using the default ID Format.
         *
         *  <p/>This method allows you to create "Well-known" PeerGroupIDs.
         *  This is similar to how the JXTA "World Peer Group" and "Net
         *  Peer Group". "Well-known" IDs can be useful for common services
         *  that need to do  discovery without advertisements or for network
         *  organization  services. Because of the potential for ID collisions
         *  and the difficulties with maintaining common service interfaces this
         *  varient of PeerGroupID should be used with great caution and
         *  pre-planning.
         *
         *  @see net.jxta.peergroup.PeerGroup
         *
         *  @param seed The seed information which will be used in creating the
         *  PeerGroupID. The seed information should be at least four bytes in
         *  length, though longer values are better.
         *  @return The newly created PeerGroupID.
         **/
        public PeerGroupID newPeerGroupID( byte [] seed );
        
        /**
         *  Creates a new PeerGroupID instance with the specified parent group.
         *  A new random peer group id will be generated.
         *
         *  @see net.jxta.peergroup.PeerGroup
         *
         *  @param parent The group which will be the parent of this group.
         *  @return The newly created PeerGroupID.
         **/
        public PeerGroupID newPeerGroupID( PeerGroupID parent );
        
        /**
         *  Creates a new PeerGroupID instance with the specified parent group.
         *  A new PeerGroupID will be generated using the provided seed
         *  information.
         *
         *  <p/>This method allows you to create "Well-known" PeerGroupIDs.
         *  This is similar to how the JXTA "World Peer Group" and "Net
         *  Peer Group". "Well-known" IDs can be useful for common services
         *  that need to do  discovery without advertisements or for network
         *  organization  services. Because of the potential for ID collisions
         *  and the difficulties with maintaining common service interfaces this
         *  varient of PeerGroupID should be used with great caution and
         *  pre-planning.
         *
         *  @see net.jxta.peergroup.PeerGroup
         *
         *  @param parent    The group which will be the parent of this group.