/*
* 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.peergroup;
import net.jxta.document.Advertisement;
import net.jxta.document.MimeMediaType;
import net.jxta.document.StructuredDocumentFactory;
import net.jxta.document.XMLDocument;
import net.jxta.document.XMLElement;
import net.jxta.exception.ConfiguratorException;
import net.jxta.exception.JxtaError;
import net.jxta.exception.PeerGroupException;
import net.jxta.id.ID;
import net.jxta.logging.Logging;
import net.jxta.protocol.ConfigParams;
import java.io.File;
import java.io.IOException;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.net.URI;
import java.net.URLConnection;
import java.util.MissingResourceException;
import java.util.PropertyResourceBundle;
import java.util.ResourceBundle;
import java.util.logging.Level;
import java.util.logging.Logger;
/**
* A factory for instantiating the JXTA core peer groups.
* <p/>
* JXTA comes with two peergroup implementations:
* <p/>
* <dl>
* <DT><strong>Platform</strong></DT>
* <DD>Implements the world peer group. Every peer starts by instantiating this
* peer group and then other peer groups are instantiated as needed. The World
* Peer Group's ID is invariant.
* <p/>
* The world peer group provides the minimum core services needed to find
* and instantiate other groups on a peer. The <strong>Platform</strong>
* implementation will assign a new ID to the peer, if it does not already have
* one.</DD>
* <p/>
* <DT><strong>StdPeergroup</strong></DT>
* <DD>This is currently used to implement all other kinds of peer groups.
* The first such peer group that it is instantiated after starting is known as
* <em>The Net Peer Group</em>. When the <strong>Platform</strong> starts it may
* optionally search for <em>The Net Peer Group</em> on the local network and,
* if found, instantiate it. Otherwise a default built-in configuration of
* <em>The Net Peer Group</em> is instantiated.
* <p/>
* A non-default configuration of <em>The Net Peer Group</em> may be set-up
* by the administrator in charge of the network domain inside which the peer
* is starting. <em>The Net Peer Group</em> is discovered via the Discovery
* protocol. Many such groups may be configured by an administrator.<br>
* <p/>
* <strong>StdPeergroup</strong> may also be used to implement User-defined
* peer groups--Users can create new peer groups which use their own set of
* customized services.</DD>
* </dl>
*
* @see net.jxta.peergroup.PeerGroup
* @deprecated This factory has been deprecated in favour of {@link WorldPeerGroupFactory}
* and {@link NetPeerGroupFactory}. See the deprecations for the individual
* methods for the specific replacements/alternatives provided by the new
* factory classes.
*/
@Deprecated
public final class PeerGroupFactory {
/**
* Logger
*/
private final static transient Logger LOG = Logger.getLogger(PeerGroupFactory.class.getName());
/**
* Constant for specifying no configurator. This configurator provides no
* configuration actions but does ensure that a valid configuration exists
* at the specified location.
*/
public final static Class NULL_CONFIGURATOR = net.jxta.impl.peergroup.NullConfigurator.class;
/**
* Constant for specifying the default configurator. Currently this is the
* familiar AWT-based dialogue but in future is likely to become the
* UI-less automatic configurator.
*/
public final static Class DEFAULT_CONFIGURATOR = net.jxta.impl.peergroup.DefaultConfigurator.class;
/**
* The class which will be instantiated as the World Peer Group.
*/
private static Class worldGroupClass = null;
/**
* The ID of the network peer group.
*/
private static PeerGroupID netPGID = null;
/**
* The name of the network peer group.
*/
private static String netPGName = null;
/**
* The description of the network peer group.
*/
private static String netPGDesc = null;
/**
* The class which will be instantiated to configure the World Peer
* Group.
*/
private static Class configurator = DEFAULT_CONFIGURATOR;
/**
* the location which will serve as the parent for all stored items used
* by JXTA.
*/
private static URI storeHome = null;
/**
* Static Method to initialize the world peer group class.
*
* @param c The Class which will be instantiated for the World Peer Group
* @deprecated Consider converting to use {@link WorldPeerGroupFactory#WorldPeerGroupFactory(Class,ConfigParams,URI)}.
*/
@Deprecated
public static void setPlatformClass(Class c) {
worldGroupClass = c;
}
/**
* Static Method to initialize the std peer group class.
*
* @param c The Class which will be instantiated for most peer groups.
* @deprecated This method previously had no effect and has been removed with no alternatives.
*/
@Deprecated
public static void setStdPeerGroupClass(Class c) {
throw new UnsupportedOperationException("This feature has been removed. (sorry)");
}
/**
* Sets the description which will be used for new net peer group instances.
*
* @param desc The description which will be used for new net peer group instances.
* @deprecated Consider converting to use {@link NetPeerGroupFactory#NetPeerGroupFactory(ConfigParams,URI,ID,String,XMLElement)}
* or {@link NetPeerGroupFactory#NetPeerGroupFactory(PeerGroup,ID,String,XMLElement)}.
*/
@Deprecated
public static void setNetPGDesc(String desc) {
netPGDesc = desc;
}
/**
* Sets the name which will be used for new net peer group instances.
*
* @param name The name which will be used for new net peer group instances.
* @deprecated Consider converting to use {@link NetPeerGroupFactory#NetPeerGroupFactory(ConfigParams,URI,ID,String,XMLElement)}
* or {@link NetPeerGroupFactory#NetPeerGroupFactory(PeerGroup,ID,String,XMLElement)}.
*/
@Deprecated
public static void setNetPGName(String name) {
netPGName = name;
}
/**
* Sets the ID which will be used for new net peer group instances.
*
* @param id The ID which will be used for new net peer group instances.
* @deprecated Consider converting to use {@link NetPeerGroupFactory#NetPeerGroupFactory(ConfigParams,URI,ID,String,XMLElement)}
* or {@link NetPeerGroupFactory#NetPeerGroupFactory(PeerGroup,ID,String,XMLElement)}.
*/
@Deprecated
public static void setNetPGID(PeerGroupID id) {
netPGID = id;
}
/**
* Get the optional configurator class for the world peer group.
*
* @return Class configurator class
* @deprecated Consider converting to use {@link NetPeerGroupFactory}.
*/
@Deprecated
public static Class getConfiguratorClass() {
return configurator;
}
/**
* Set the optional configurator class for the World Peer Group. If present
* an instance of this class will be used to generate/update the
* configuration parameters for the World Peer Group whenever
* {@code newPlatform()} is invoked.
* <p/>
* All configuration actions for the World Peer Group may be completely
* disabled by specify {@code null} as the configurator class. The default
* configuration class is always initialized to {@code DEFAULT_CONFIGURATOR}.
*
* @param c The {@code Class} to use as a configurator for the World Peer
* Group.
* @deprecated Consider converting to use {@link NetPeerGroupFactory} and/or {@link WorldPeerGroupFactory}.
*/
@Deprecated
public static void setConfiguratorClass(Class c) {
if (Logging.SHOW_FINE && LOG.isLoggable(Level.FINE)) {
LOG.fine("Setting configurator class to : " + c);
}
configurator = c;
}
/**
* Returns the location which will serve as the parent for all stored items
* used by JXTA. This method is intended for use by PeerGroup implementations
* and is not intended for use by applications. Applications and services
* should use the PeerGroup method with the same name.
*
* @return The location which will serve as the parent for all stored
* items used by JXTA.
* @see PeerGroup#getStoreHome()
* @deprecated Consider converting to use {@link NetPeerGroupFactory} and/or {@link WorldPeerGroupFactory}.
*/
@Deprecated
public static URI getStoreHome() {
if (null == storeHome) {
// Establish the default store location via long established hackery.
String jxta_path = System.getProperty("JXTA_HOME", ".jxta/");
File jxta_home = new File(jxta_path);
jxta_home.mkdirs();
URI defaultHome = jxta_home.toURI();
return defaultHome;
}
return storeHome;
}
/**
* Set the location which will serve as the parent for all stored items used by JXTA.
*
* @param newHome The absolute URI location which will serve as the parent
* for all stored items used by JXTA. Currently this must be a non-opaque URI.
* May also be {@code null} to restore the default value.
* @deprecated Consider converting to use {@link NetPeerGroupFactory} and/or {@link WorldPeerGroupFactory}.
*/
@Deprecated
public static void setStoreHome(URI newHome) {
if (null != newHome) {
// Fail if the URI is not absolute.
if (!newHome.isAbsolute()) {
throw new IllegalArgumentException("Only absolute URIs accepted for store home location.");
}
// Fail if the URI is Opaque.
if (newHome.isOpaque()) {
throw new IllegalArgumentException("Only hierarchical URIs accepted for store home location.");
}
// Add a trailing slash if necessary.
if (!newHome.toString().endsWith("/")) {
newHome = URI.create(newHome.toString() + "/");
}
}
storeHome = newHome;
}
/**
* Static Method to create a new peer group instance.
* <p/>
* After being created the init() method needs to be called, and
* the startApp() method may be called, at the invoker's discretion.
*
* @return PeerGroup instance of a new PeerGroup
* @deprecated This method was previously unused and has been removed with no alternatives. (it wasn't useful)
*/
@Deprecated
public static PeerGroup newPeerGroup() {
throw new UnsupportedOperationException("This feature has been removed. (sorry)");
}
/**
* Instantiates the World (Platform) Peer Group and can also optionally
* (re)configure the world peer group before instantiation using the
* configurator specified via {@link #setConfiguratorClass(Class)}.
* <p/>
* Only one instance of the World Peer Group may be created within the
* context of the {@code PeerGroupFactory}'s class loader. Invoking this
* method amounts to creating an instance of JXTA.
* <p/>
* The {@link PeerGroup#init(PeerGroup,ID,Advertisement)} method is
* called automatically. The {@link PeerGroup#startApp(String[])} method
* is left for the invoker to call if appropriate.
*
* @return PeerGroup The World Peer Group instance.
* @throws JxtaError Thrown for all checked Exceptions which occur during
* construction of the World Peer Group.
* @deprecated Consider converting to use {@link WorldPeerGroupFactory#WorldPeerGroupFactory()}.
*/
@Deprecated
public static PeerGroup newPlatform() {
Class c = PeerGroupFactory.getConfiguratorClass();
if (null == c) {
c = NULL_CONFIGURATOR;
}
Configurator configurator;
try {
Constructor config_constructor = c.getConstructor(URI.class);
configurator = (Configurator) config_constructor.newInstance(getStoreHome());
} catch (InvocationTargetException ie) {
LOG.log(Level.SEVERE, "Uninstantiatable configurator: " + c, ie);
throw new JxtaError("Uninstantiatable configurator: " + c, ie);
} catch (NoSuchMethodException ie) {
LOG.log(Level.SEVERE, "Uninstantiatable configurator: " + c, ie);
throw new JxtaError("Uninstantiatable configurator: " + c, ie);
} catch (InstantiationException ie) {
LOG.log(Level.SEVERE, "Uninstantiatable configurator: " + c, ie);
throw new JxtaError("Uninstantiatable configurator: " + c, ie);
} catch (IllegalAccessException iae) {
LOG.log(Level.SEVERE, "can\'t instantiate configurator: " + c, iae);
throw new JxtaError("Can't instantiate configurator: " + c, iae);
} catch (ClassCastException cce) {
LOG.log(Level.SEVERE, "Not a Configurator :" + c, cce);
throw new JxtaError("Not a Configurator :" + c, cce);
}
ConfigParams pc;
try {
pc = configurator.getConfigParams();
} catch (ConfiguratorException cce) {
LOG.log(Level.SEVERE, "Could not retrieve configuration", cce);
throw new JxtaError("Could not retrieve configuration", cce);
}
try {
WorldPeerGroupFactory wpgf;
if (null == worldGroupClass) {
wpgf = new WorldPeerGroupFactory(pc, getStoreHome());
} else {
wpgf = new WorldPeerGroupFactory(worldGroupClass, pc, getStoreHome());
}
configurator.setConfigParams(pc);
configurator.save();
// Forget about the configurator
configurator = null;
return wpgf.getInterface();
} catch (RuntimeException e) {
if (Logging.SHOW_SEVERE && LOG.isLoggable(Level.SEVERE)) {
LOG.log(Level.SEVERE, "newPlatform failed", e);
}
// rethrow
throw e;
} catch (Exception e) {
// should be all other checked exceptions
if (Logging.SHOW_SEVERE && LOG.isLoggable(Level.SEVERE)) {
LOG.log(Level.SEVERE, "newPlatform failed", e);
}
// Simplify exception scheme for caller: any sort of problem wrapped
// in a PeerGroupException.
throw new JxtaError("newPlatform failed", e);
} catch (Error e) {
if (Logging.SHOW_SEVERE && LOG.isLoggable(Level.SEVERE)) {
LOG.log(Level.SEVERE, "newPlatform failed", e);
}
// rethrow
throw e;
}
}
/**
* Instantiates the net peer group using the provided parent peer group.
*
* @param ppg The parent group.
* @return PeerGroup The default netPeerGroup
* @throws PeerGroupException For failures in constructing the Net Peer Group.
* @deprecated Consider converting to use {@link NetPeerGroupFactory#NetPeerGroupFactory(PeerGroup,ID,String,XMLElement)}.
*/
@Deprecated
public static PeerGroup newNetPeerGroup(PeerGroup ppg) throws PeerGroupException {
try {
NetPeerGroupFactory npgf;
NetPeerGroupFactory.NetGroupTunables tunables;
if (null == netPGID) {
// Determine net peer group configuration parameters if they
// have not already been set.
tunables = new NetPeerGroupFactory.NetGroupTunables(ResourceBundle.getBundle("net.jxta.impl.config")
,
new NetPeerGroupFactory.NetGroupTunables());
// load overides from "${JXTA_HOME}config.properties".
URI configPropertiesLocation = getStoreHome().resolve("config.properties");
try {
URLConnection configProperties = configPropertiesLocation.toURL().openConnection();
ResourceBundle rsrcs = new PropertyResourceBundle(configProperties.getInputStream());
tunables = new NetPeerGroupFactory.NetGroupTunables(rsrcs, tunables);
if (Logging.SHOW_FINE && LOG.isLoggable(Level.FINE)) {
LOG.fine("Loaded defaults from " + rsrcs);
}
} catch (MissingResourceException ignored) {
;
} catch (IOException ignored) {
;
} catch (Exception ignored) {
;
}
} else {
tunables = new NetPeerGroupFactory.NetGroupTunables(netPGID, netPGName
,
(XMLDocument) StructuredDocumentFactory.newStructuredDocument(MimeMediaType.XMLUTF8, "desc", netPGDesc));
}
npgf = new NetPeerGroupFactory(ppg, tunables.id, tunables.name, tunables.desc);
PeerGroup newPg = npgf.getInterface();
return newPg;
} catch (PeerGroupException failed) {
if (Logging.SHOW_SEVERE && LOG.isLoggable(Level.SEVERE)) {
LOG.log(Level.SEVERE, "newNetPeerGroup failed", failed);
}
// rethrow
throw failed;
} catch (RuntimeException e) {
if (Logging.SHOW_SEVERE && LOG.isLoggable(Level.SEVERE)) {
LOG.log(Level.SEVERE, "newNetPeerGroup failed", e);
}
// rethrow
throw e;
} catch (Exception e) {
// should be all other checked exceptions
if (Logging.SHOW_SEVERE && LOG.isLoggable(Level.SEVERE)) {
LOG.log(Level.SEVERE, "newNetPeerGroup failed", e);
}
// Simplify exception scheme for caller: any sort of problem wrapped
// in a PeerGroupException.
throw new PeerGroupException("newNetPeerGroup failed", e);
} catch (Error e) {
if (Logging.SHOW_SEVERE && LOG.isLoggable(Level.SEVERE)) {
LOG.log(Level.SEVERE, "newNetPeerGroup failed", e);
}
// rethrow
throw e;
}
}
/**
* Instantiates the World Peer Group and then instantiates the Net Peer
* Group. This simplifies the method by which applications can start JXTA.
*
* @return The newly instantiated Net Peer Group.
* @deprecated Consider converting to use {@link NetPeerGroupFactory#NetPeerGroupFactory()}
* or preferably one of the other {@code NetPeerGroupFactory} constructors.
*/
@Deprecated
public static PeerGroup newNetPeerGroup() throws PeerGroupException {
// get/create the World Peer Group.
PeerGroup wpg = getWorldPeerGroup();
try {
PeerGroup npg = newNetPeerGroup(wpg);
return npg;
} finally {
wpg.unref();
}
}
/**
* Retrieves or constructs a new World Peer Group instance suitable for
* use as the parent for Net Peer Group instances. This implementation
* makes an important trade-off worth noting; it will use an existing
* world peer group instance if available and ignore any changes which have
* been made to the static configuration methods provided by this class.
*
* @return The World Peer Group.
* @throws PeerGroupException For failures in recovering the World Peer Group.
*/
private static PeerGroup getWorldPeerGroup() throws PeerGroupException {
synchronized (PeerGroup.globalRegistry) {
PeerGroup result = PeerGroup.globalRegistry.lookupInstance(PeerGroupID.worldPeerGroupID);
if (null != result) {
return result;
}
return newPlatform();
}
}
}