idfactory.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.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 java.util.logging.Level;
import net.jxta.logging.Logging;
import java.util.logging.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="https://jxta-spec.dev.java.net/nonav/JXTAProtocols.html#ids" target='_blank'>JXTA Protocols Specification : IDs</a>
 */
public final class IDFactory extends ClassFactory<String, IDFactory.Instantiator> {
    
    /**
     *  Logger
     */
    private static final transient Logger LOG = Logger.getLogger(IDFactory.class.getName());
    
    /**
     *  A map of the ID Formats to instantiators.
     *
     */
    private final Map<String, Instantiator> idFormats = new HashMap<String, Instantiator>();
    
    /**
     *  Identifies the ID format to use when creating new ID instances.
     */
    private final String idNewInstances;
    
    /**
     *  This class is a singleton. This is the instance that backs the
     *  static methods.
     */
    private final static IDFactory factory = new IDFactory();
    
    /**
     *  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 {@code 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.
         */
        @Deprecated
        public ID fromURL(URL source) throws MalformedURLException, UnknownServiceException;
        
        /**
         *  Construct a new ID instance from a JXTA ID contained in a URI.
         *
         *  @param source  URI which will be decoded to create a new ID instance.
         *  @return  ID containing the new ID instance initialized from the source.
         *  @throws URISyntaxException if the URI provided is not a valid,
         *  recognized JXTA URI.
         */
        public ID fromURI(URI source) throws URISyntaxException;
        
        /**
         *  Construct a new ID instance from the scheme specific portion of a jxta
         *  URN.
         *
         *  @param source  the scheme specific portion of a jxta URN.
         *  @return  ID containing the new ID instance initialized from the source.
         *  @throws URISyntaxException if the URI provided is not a valid,
         *  recognized JXTA URI.
         */
        public ID fromURNNamespaceSpecificPart(String source) throws URISyntaxException;

        /**
         *  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 variant 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 variant 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 variant 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 variant 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