idfactory.java

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

         *  @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( PeerGroupID parent, byte [] seed );
        
        /**
         *  Creates a new PipeID instance. A new random PipeID will be generated.
         *
         *
         *  @param groupID  The group to which this Pipe ID will belong.
         *  @return The newly created PipeID.
         **/
        public PipeID newPipeID( PeerGroupID groupID );
        
        /**
         *  Creates a new PipeID instance. A new pipe id will be generated with
         *  the provided seed information. The Pipe ID will be a member of the
         *  provided group.
         *
         *  <p/>This varient of PipeID allows you to create "Well-known" pipes
         *  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 PipeID should be used with great caution
         *  and pre-planning.
         *
         *
         *  @param groupID  the group to which this Pipe ID will belong.
         *  @param seed The seed information which will be used in creating the
         *  pipeID. The seed information should be at least four bytes in
         *  length, though longer values are better.
         *  @return the newly created PipeID.
         **/
        public PipeID newPipeID( PeerGroupID groupID, byte [] seed );
        
        /**
         *  Creates a new ModuleClassID instance. A new random ModuleClassID
         *  will be generated with a zero value role identifier. This form of
         *  ModuleClassID is appropriate for cases where the module does not
         *  need to be distinguished from other instances of the same Module.
         *  The ModuleClassID will be created using the default ID Format.
         *
         *  @see net.jxta.platform.Module
         *
         *  @return The newly created ModuleClassID.
         **/
        public ModuleClassID newModuleClassID( );
        
        /**
         *  Creates a new ModuleClassID instance. A new random ModuleClassID
         *  will be generated with a a random value role identifier and a base
         *  class of the provided ModuleClassID. This form of ModuleClassID is
         *  appropriate for cases where it is necessary to distinguish instances
         *  of the same service interface.
         *
         *  @see net.jxta.platform.Module
         *
         *  @param  baseClass   The ModuleClassID which will be used as a base
         *  class for this new role value instance.
         *  @return The newly created ModuleClassID.
         **/
        public ModuleClassID newModuleClassID( ModuleClassID baseClass );
        
        /**
         *  Creates a new  ModuleSpecID instance. A new random ModuleSpecID will
         *  be generated.
         *
         *  @see net.jxta.platform.Module
         *
         *  @param baseClass   The ModuleClassID which will be used as a base
         *  class for this new ModuleSpecID.
         *  @return The newly created ModuleSpecID.
         **/
        public ModuleSpecID newModuleSpecID( ModuleClassID baseClass );
    }
    
    /**
     *  Extended instantiator which provides for construction from URIs and from
     * scheme specific URN fragments. ID Formats are not required to implement
     * this interface, but doing so will improve performance in many cases.
     * When the deprecated URL based calls are removed these methods will be
     * added to the primary interface and this interface will be deprecated.
     **/
    public interface URIInstantiator extends Instantiator {
        
        /**
         *  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;
    }
    
    /**
     *  Log4J Logger
     **/
    private static final transient Logger LOG = Logger.getLogger(IDFactory.class.getName());
    
    /**
     *  A map of the ID Formats to instantiators.
     *
     *  <ul>
     *      <li>keys are {@link java.lang.String} of ID Format names</li>
     *      <li>values are {@link Instantiator} instances</li>
     *  </ul>
     **/
    private final Map idFormats = new HashMap();
    
    /**
     *  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();
    
    /**
     *  Standard Constructor. This class is a singleton so the only constructor
     *  is private.
     *
     *  <p/>Registers the pre-defined set of ID sub-classes so that this factory
     *  can construct them. Uses net.jxta.impl.config.properties file as the
     *  source for settings.
     *
     * <p/>Example entry from  the file net.jxta.impl.config.properties :
     *
     * <p/><pre><code>
     * #List of ID types supported.
     * IDInstanceTypes=net.jxta.id.jxta.IDFormat net.jxta.impl.id.UUID.IDFormat net.jxta.impl.id.binaryID.IDFormat
     *
     * #Default type of ID to use when creating an ID (this should not be changed in most implementations).
     * IDNewInstances=uuid
     * </code></pre>
     **/
    private IDFactory() {
        // required format
        registerAssoc( "net.jxta.id.jxta.IDFormat" );
        
        // required by this implementation.
        registerAssoc( "net.jxta.impl.id.unknown.IDFormat" );
        
        try {
            // Get our resource bundle
            ResourceBundle jxtaRsrcs = ResourceBundle.getBundle( "net.jxta.impl.config" );
            
            // set the default ID Format.
            idNewInstances = jxtaRsrcs.getString( "IDNewInstances" ).trim();
            
            // Register a list of classes for association with an ID type
            registerFromResources( "net.jxta.impl.config",  "IDInstanceTypes" );
        } catch ( MissingResourceException notFound ) {
            // This is an error because we can't start without a concept of ID.
            LOG.fatal( "Could not find net.jxta.impl.config properties file! reason:" ,notFound );
            IllegalStateException failure = new IllegalStateException( "Could not initialize ID defaults");
            failure.initCause(notFound);
            
            throw failure;
        }
    }
    
    /**
     *  Used by ClassFactory methods to get the mapping of ID types to constructors.
     *
     *  @return Hashtable the hashtable containing the mappings.
     **/
    protected Map getAssocTable() {
        return idFormats;
    }
    
    /**
     *  Used by ClassFactory methods to ensure that all keys used with the mapping are
     *  of the correct type.
     *
     *  @return Class object of the key type.
     **/
    protected Class getClassForKey() {
        return String.class;
    }
    
    /**
     *  Used by ClassFactory methods to ensure that all of the instance classes
     *  which register with this factory have the correct base class
     *
     *  @return Class object of the key type.
     **/
    protected Class getClassOfInstantiators() {
        // we dont require that they be of any particular type since they are
        // factories themselves
        return Object.class;
    }
    
    /**
     *  Register a class with the factory from its class name. We override the
     *  standard implementation to get the id format from the class and
     *  use that as the key to register the class with the factory.
     *
     * @param className The class name which will be regiestered.
     * @return boolean true if the class was registered otherwise false.
     */
    public boolean registerAssoc( String className ) {
        boolean registeredSomething = false;
        
        try {
            Class idClass;
            try {
                idClass = Class.forName( className );
                
                if( null == idClass ) {
                    throw new ClassNotFoundException( "forName() result was null" );
                }
            } catch( ClassNotFoundException notThere ) {
                LOG.error( "Could not find class named : " + className );
                return false;
            }  catch( NoClassDefFoundError notThere ) {
                LOG.error( "Could not find class named : " + className );
                return false;
            }
            
            Field instantiatorField;
            try {
                instantiatorField = idClass.getField("INSTANTIATOR");
                
                if( null == instantiatorField ) {
                    throw new NoSuchFieldException( "getField() result was null for field 'INSTANTIATOR'" );
                    // caught locally
                }
            } catch( NoSuchFieldException notThere ) {
                LOG.error( "Could not find INSTANTIATOR field in class named : " + className );
                return false;
            }
            
            if( !Instantiator.class.isAssignableFrom( instantiatorField.getType() ) ) {
                throw new ClassCastException( "INSTANTIATOR is not of type " + Instantiator.class.getName() );
            }
            
            Instantiator instantiator = (Instantiator) instantiatorField.get(null);
            
            if( null == instantiator ) {
                LOG.error( "INSTANTIATOR field is null for class  : " + className );
                return false;
            }
            
            String idFormat = instantiator.getSupportedIDFormat( );
            
            registeredSomething = registerAssoc( idFormat, instantiator );
        } catch( Exception failed ) {
            LOG.error( "Failed to register class : " + className, failed );
        }
        
        return registeredSomething;
    }
    
    /**
     *  Returns a String containing the name of the default ID Format.
     *
     *  @return The current default ID Format.
     **/
    public static String getDefaultIDFormat( ) {
        return factory.idNewInstances;
    }
    
    /**
     *  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 URI.
     *  @throws URISyntaxException If the URI provided is not a valid,
     *  recognized JXTA URI.
     **/
    public static ID fromURI(URI source) throws URISyntaxException {
        ID result = null;
        
        // check the protocol
        if ( !ID.URIEncodingName.equalsIgnoreCase(source.getScheme()) ) {
            throw new URISyntaxException( source.toString(), "URI scheme was not as expected." );
        }
        
        String decoded = source.getSchemeSpecificPart();
        
        int colonAt = decoded.indexOf( ':' );
        
        // There's a colon right?
        if( -1 == colonAt ) {
            throw new URISyntaxException( source.toString(), "URN namespace was missing." );