/**
* Looks a configuration object using the preference store and extension points to locate the
* class and instantiate it. If there is a problem, null is returned and the caller is expect to
* supply a default value of their own. Exceptions are not thrown, but messages will be logged.
*
* <p>These configuration objects are typically defined in plugin_customization.ini files, and
* these values are loaded into the preference store. The parameter <tt>prefConstant</tt> is used
* to look up this value, and should be the key (prefixed by the plug-in name,
* org.locationtech.udig.ui) used in the ini file.
*
* <p>The returned object will either be an instances of <tt>interfaceClass</tt> or <tt>null</tt>.
*
* <p>The parameter <tt>xpid</tt> is the extension point ID that the value specified in the ini
* file should point to. This extension point must contain an attribute used for an id, and an
* attribute used for the class which is an implementation of <tt>interfaceClass</tt>.
* <tt>idField</tt> indicates the name of the attribute for id, and <tt>classField</tt> indicates
* the name of the attribute for the class.
*
* <p>Example: plugin_customization.ini
*
* <pre>
* org.locationtech.udig.ui/workbenchConfiguration=org.locationtech.udig.internal.ui.UDIGWorkbenchConfiguration
* </pre>
*
* <b><tt>store</tt></b>: org.locationtech.udig.internal.ui.UiPlugin.getPreferenceStore() (this
* corresponds to the first part of the key)
*
* <p><b><tt>pluginID</tt></b>: "org.locationtech.udig.ui"
*
* <p><b><tt>prefConstant</tt></b>: "workbenchConfiguration"
*
* <pre>
* <extension
* point="org.locationtech.udig.ui.workbenchConfigurations">
* <workbenchConfiguration
* class="org.locationtech.udig.internal.ui.UDIGWorkbenchConfiguration"
* id="org.locationtech.udig.internal.ui.UDIGWorkbenchConfiguration"/>
* </extension>
* </pre>
*
* <b><tt>xpid</tt></b>: "org.locationtech.udig.ui.workbenchConfigurations"
* <b><tt>idField</tt></b>: "id" <b><tt>classField</tt></b>: "class"
*
* <p>This will return an instance of <tt>org.locationtech.udig.ui.WorkbenchConfiguration</tt>, or
* null if it cannot find one (in which case, check the logs!).
*
* <p>Make sure to be a good developer and use constants. Also make sure to use a default
* implementation if this returns null! The code should not explode!
*
* <p>TODO It would be nice to simplify this API call.
*
* @param interfaceClass instance of the interface that will be instantiated and returned
* @param store the preference store used to lookup prefConstant
* @param pluginID the ID of the plug-in that the preference store lives
* @param prefConstant key used in plugin_customization.ini
* @param xpid extension point id key
* @param idField id attribute key used in extension point
* @param classField class attribute key used in extension point
*/
public static Object lookupConfigurationObject(
Class<?> interfaceClass,
final IPreferenceStore store,
final String pluginID,
final String prefConstant,
final String xpid,
final String idField,
final String classField) {
final String configurationID = store.getString(prefConstant);
if (configurationID != null && !configurationID.equals("")) {
try {
final Object[] configObj = new Object[1];
final Throwable[] error = new Throwable[1];
ExtensionPointProcessor p =
new ExtensionPointProcessor() {
public void process(IExtension extension, IConfigurationElement element)
throws Exception {
try {
if (element.getAttribute(idField) != null
&& element.getAttribute(idField).equals(configurationID)) {
Object obj = element.createExecutableExtension(classField);
configObj[0] = obj;
}
} catch (Exception e) {
configObj[0] = null;
error[0] = e;
}
}
};
ExtensionPointUtil.process(getDefault(), xpid, p);
if (configObj[0] != null) {
return configObj[0];
} else {
MessageFormat format =
new MessageFormat(Messages.UDIGWorkbenchWindowAdvisor_specifiedButNotFound);
Object[] args = new Object[] {configurationID, interfaceClass.getName()};
StringBuffer message = format.format(args, new StringBuffer(), null);
Throwable e = null;
if (error[0] != null) {
e = error[0];
}
trace(message.toString(), e);
}
} catch (Exception e) {
log(
MessageFormat.format(
Messages.UDIGWorkbenchWindowAdvisor_classNotFound,
new Object[] {configurationID},
interfaceClass.getName()),
e);
}
}
return null;
}
/**
* Adds the name of the caller class to the message.
*
* @param caller class of the object doing the trace.
* @param message tracing message, may be null.
* @param e exception, may be null.
*/
public static void trace(Class<?> caller, String message, Throwable e) {
trace(caller.getSimpleName() + ": " + message, e); // $NON-NLS-1$ //$NON-NLS-2$
}
/**
* Messages that only engage if getDefault().isDebugging() and the trace option traceID is true.
* Available trace options can be found in the Trace class. (They must also be part of the
* .options file)
*/
public static void trace(String traceID, Class<?> caller, String message, Throwable e) {
if (isDebugging(traceID)) {
trace(caller, message, e);
}
}