diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterFactoryProxy.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterFactoryProxy.java
index 66c51b6b6f1..f848a33aad2 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterFactoryProxy.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterFactoryProxy.java
@@ -41,15 +41,15 @@ class AdapterFactoryProxy implements IAdapterFactory, IAdapterFactoryExt {
private Optional
- * Please read bug 515587 for details.
+ * Please read
+ * bug
+ * 515587 for details.
*/
@Override
public String toString() {
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ConfigurationElementMulti.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ConfigurationElementMulti.java
index b6631632f15..2d43d5126b5 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ConfigurationElementMulti.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ConfigurationElementMulti.java
@@ -14,8 +14,8 @@
package org.eclipse.core.internal.registry;
/**
- * An object which represents the user-defined contents of an extension
- * in a plug-in manifest.
+ * An object which represents the user-defined contents of an extension in a
+ * plug-in manifest.
*/
public class ConfigurationElementMulti extends ConfigurationElement {
@@ -28,15 +28,18 @@ protected ConfigurationElementMulti(ExtensionRegistry registry, boolean persist)
super(registry, persist);
}
- protected ConfigurationElementMulti(int self, String contributorId, String name, String[] propertiesAndValue, int[] children, int extraDataOffset, int parent, byte parentType, ExtensionRegistry registry, boolean persist) {
- super(self, contributorId, name, propertiesAndValue, children, extraDataOffset, parent, parentType, registry, persist);
+ protected ConfigurationElementMulti(int self, String contributorId, String name, String[] propertiesAndValue,
+ int[] children, int extraDataOffset, int parent, byte parentType, ExtensionRegistry registry,
+ boolean persist) {
+ super(self, contributorId, name, propertiesAndValue, children, extraDataOffset, parent, parentType, registry,
+ persist);
}
@Override
String getAttribute(String attrName, String locale) {
if (propertiesAndValue.length <= 1)
return null;
- //round down to an even size
+ // round down to an even size
int size = propertiesAndValue.length - (propertiesAndValue.length % 2);
int index = -1;
for (int i = 0, j = 0; i < size; i += 2, j++) {
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Contribution.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Contribution.java
index 3789c7f75b0..9903fd57297 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Contribution.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Contribution.java
@@ -20,9 +20,9 @@
// It is mainly used on removal so we can quickly find objects to remove.
// Each contribution is made in the context of a namespace.
public class Contribution implements KeyedElement {
- static final int[] EMPTY_CHILDREN = new int[] {0, 0};
+ static final int[] EMPTY_CHILDREN = new int[] { 0, 0 };
- //The registry that owns this object
+ // The registry that owns this object
protected ExtensionRegistry registry;
// The actual contributor of the contribution
@@ -34,11 +34,14 @@ public class Contribution implements KeyedElement {
// indicates if this contribution needs to be saved in the registry cache
protected boolean persist;
- // This array stores the identifiers of both the extension points and the extensions.
+ // This array stores the identifiers of both the extension points and the
+ // extensions.
// The array has always a minimum size of 2.
- // The first element of the array is the number of extension points and the second the number of extensions.
- // [numberOfExtensionPoints, numberOfExtensions, extensionPoint#1, extensionPoint#2, extensionPoint..., ext#1, ext#2, ext#3, ... ].
- // The size of the array is 2 + (numberOfExtensionPoints + numberOfExtensions).
+ // The first element of the array is the number of extension points and the
+ // second the number of extensions.
+ // [numberOfExtensionPoints, numberOfExtensions, extensionPoint#1,
+ // extensionPoint#2, extensionPoint..., ext#1, ext#2, ext#3, ... ].
+ // The size of the array is 2 + (numberOfExtensionPoints + numberOfExtensions).
private int[] children = EMPTY_CHILDREN;
static final public byte EXTENSION_POINT = 0;
static final public byte EXTENSION = 1;
@@ -55,10 +58,10 @@ void mergeContribution(Contribution addContribution) {
// persist?
// Old New Result
- // F F F
- // F T T => needs to be adjusted
- // T F T
- // T T T
+ // F F F
+ // F T T => needs to be adjusted
+ // T F T
+ // T T T
if (shouldPersist() != addContribution.shouldPersist())
persist = true;
@@ -73,8 +76,10 @@ void mergeContribution(Contribution addContribution) {
System.arraycopy(existing, 2, allChildren, 2, existing[EXTENSION_POINT]);
System.arraycopy(addition, 2, allChildren, 2 + existing[EXTENSION_POINT], addition[EXTENSION_POINT]);
allChildren[EXTENSION] = extensions;
- System.arraycopy(existing, 2 + existing[EXTENSION_POINT], allChildren, 2 + extensionPoints, existing[EXTENSION]);
- System.arraycopy(addition, 2 + addition[EXTENSION_POINT], allChildren, 2 + extensionPoints + existing[EXTENSION], addition[EXTENSION]);
+ System.arraycopy(existing, 2 + existing[EXTENSION_POINT], allChildren, 2 + extensionPoints,
+ existing[EXTENSION]);
+ System.arraycopy(addition, 2 + addition[EXTENSION_POINT], allChildren,
+ 2 + extensionPoints + existing[EXTENSION], addition[EXTENSION]);
children = allChildren;
}
@@ -114,7 +119,7 @@ public String toString() {
return "Contribution: " + contributorId + " in namespace" + getDefaultNamespace(); //$NON-NLS-1$ //$NON-NLS-2$
}
- //Implements the KeyedElement interface
+ // Implements the KeyedElement interface
@Override
public int getKeyHashCode() {
return getKey().hashCode();
@@ -169,6 +174,7 @@ public boolean isEmpty() {
/**
* Find if this contribution has a children with ID = id.
+ *
* @param id possible ID of the child
* @return true: contribution has this child
*/
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/DirectMap.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/DirectMap.java
index cddb96333c3..c95fa573a58 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/DirectMap.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/DirectMap.java
@@ -16,9 +16,9 @@
/**
* Essentially a map String -> String[] for small number of keys.
*
- * For Maps containing a small number of objects hashing often reduces performance.
- * This implementation uses two parallel arrays, one for keys, one for
- * values, and grows them as necessary.
+ * For Maps containing a small number of objects hashing often reduces
+ * performance. This implementation uses two parallel arrays, one for keys, one
+ * for values, and grows them as necessary.
*/
public class DirectMap {
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Extension.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Extension.java
index 86562bfa79c..de0952556a1 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Extension.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Extension.java
@@ -23,16 +23,18 @@
public class Extension extends RegistryObject {
public static final Extension[] EMPTY_ARRAY = new Extension[0];
- //Extension simple identifier
+ // Extension simple identifier
private String simpleId;
- //The namespace for the extension.
+ // The namespace for the extension.
private String namespaceIdentifier;
- // Place holder for the label and the extension point. It contains either a String[] or a SoftReference to a String[].
- //The array layout is [label, extension point name]
+ // Place holder for the label and the extension point. It contains either a
+ // String[] or a SoftReference to a String[].
+ // The array layout is [label, extension point name]
private Object extraInformation;
- private static final byte LABEL = 0; //The human readable name of the extension
- private static final byte XPT_NAME = 1; // The fully qualified name of the extension point to which this extension is attached to
+ private static final byte LABEL = 0; // The human readable name of the extension
+ private static final byte XPT_NAME = 1; // The fully qualified name of the extension point to which this extension
+ // is attached to
private static final byte CONTRIBUTOR_ID = 2; // ID of the actual contributor of this extension
private static final int EXTRA_SIZE = 3;
@@ -40,7 +42,8 @@ protected Extension(ExtensionRegistry registry, boolean persist) {
super(registry, persist);
}
- protected Extension(int self, String simpleId, String namespace, int[] children, int extraData, ExtensionRegistry registry, boolean persist) {
+ protected Extension(int self, String simpleId, String namespace, int[] children, int extraData,
+ ExtensionRegistry registry, boolean persist) {
super(registry, persist);
setObjectId(self);
@@ -76,16 +79,18 @@ void setSimpleIdentifier(String value) {
}
private String[] getExtraData() {
- //The extension has been created by parsing, or does not have any extra data
+ // The extension has been created by parsing, or does not have any extra data
if (noExtraData()) {
if (extraInformation != null)
return (String[]) extraInformation;
return null;
}
- //The extension has been loaded from the cache.
+ // The extension has been loaded from the cache.
String[] result = null;
- if (extraInformation == null || (result = ((extraInformation instanceof SoftReference) ? (String[]) ((SoftReference>) extraInformation).get() : (String[]) extraInformation)) == null) {
+ if (extraInformation == null || (result = ((extraInformation instanceof SoftReference)
+ ? (String[]) ((SoftReference>) extraInformation).get()
+ : (String[]) extraInformation)) == null) {
result = registry.getTableReader().loadExtensionExtraData(getExtraDataOffset());
extraInformation = new SoftReference<>(result);
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionDelta.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionDelta.java
index 9ea60b750a1..0e14f074f1c 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionDelta.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionDelta.java
@@ -62,15 +62,16 @@ public void setKind(int kind) {
@Override
public String toString() {
- return "\n\t\t" + getExtensionPoint().getUniqueIdentifier() + " - " + getExtension().getNamespaceIdentifier() + '.' + getExtension().getSimpleIdentifier() + " (" + getKindString(this.getKind()) + ")"; //$NON-NLS-1$ //$NON-NLS-2$ //$NON-NLS-3$ //$NON-NLS-4$
+ return "\n\t\t" + getExtensionPoint().getUniqueIdentifier() + " - " + getExtension().getNamespaceIdentifier() //$NON-NLS-1$ //$NON-NLS-2$
+ + '.' + getExtension().getSimpleIdentifier() + " (" + getKindString(this.getKind()) + ")"; //$NON-NLS-1$ //$NON-NLS-2$
}
public static String getKindString(int kind) {
switch (kind) {
- case ADDED :
- return "ADDED"; //$NON-NLS-1$
- case REMOVED :
- return "REMOVED"; //$NON-NLS-1$
+ case ADDED:
+ return "ADDED"; //$NON-NLS-1$
+ case REMOVED:
+ return "REMOVED"; //$NON-NLS-1$
}
return "UNKNOWN"; //$NON-NLS-1$
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionHandle.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionHandle.java
index f257eaf2439..5a929050c7c 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionHandle.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionHandle.java
@@ -14,9 +14,9 @@
package org.eclipse.core.internal.registry;
/**
- * The code (minus the getDeclaringPluginDescriptor() was moved into
- * the BaseExtensionPointHandle to avoid duplicating code in the
- * compatibility fragment.
+ * The code (minus the getDeclaringPluginDescriptor() was moved into the
+ * BaseExtensionPointHandle to avoid duplicating code in the compatibility
+ * fragment.
*
* Modifications to the code should be done in the BaseExtensionHandle.
*
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionMulti.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionMulti.java
index 896a26d9cf5..dda76bd7c61 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionMulti.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionMulti.java
@@ -22,14 +22,15 @@ protected ExtensionMulti(ExtensionRegistry registry, boolean persist) {
super(registry, persist);
}
- protected ExtensionMulti(int self, String simpleId, String namespace, int[] children, int extraData, ExtensionRegistry registry, boolean persist) {
+ protected ExtensionMulti(int self, String simpleId, String namespace, int[] children, int extraData,
+ ExtensionRegistry registry, boolean persist) {
super(self, simpleId, namespace, children, extraData, registry, persist);
}
@Override
protected String getLabel(String locale) {
// this method call should be fairly rare, so no caching to save on memory
- String[] translated = registry.translate(new String[] {getLabelAsIs()}, getContributor(), locale);
+ String[] translated = registry.translate(new String[] { getLabelAsIs() }, getContributor(), locale);
return translated[0];
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPoint.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPoint.java
index 22c0832d175..29afd851778 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPoint.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPoint.java
@@ -18,21 +18,23 @@
import org.eclipse.core.runtime.IContributor;
/**
- * An object which represents the user-defined extension point in a
- * plug-in manifest.
+ * An object which represents the user-defined extension point in a plug-in
+ * manifest.
*/
public class ExtensionPoint extends RegistryObject {
public static final ExtensionPoint[] EMPTY_ARRAY = new ExtensionPoint[0];
- //Place holder for the label and the schema. It contains either a String[] or a SoftReference to a String[].
- //The array layout is [label, schemaReference, fullyQualifiedName, namespace, contributorId]
+ // Place holder for the label and the schema. It contains either a String[] or a
+ // SoftReference to a String[].
+ // The array layout is [label, schemaReference, fullyQualifiedName, namespace,
+ // contributorId]
private Object extraInformation;
- //Indexes of the various fields
- private static final byte LABEL = 0; //The human readable name for the extension point
- private static final byte SCHEMA = 1; //The schema of the extension point
- private static final byte QUALIFIED_NAME = 2; //The fully qualified name of the extension point
- private static final byte NAMESPACE = 3; //The name of the namespace of the extension point
- private static final byte CONTRIBUTOR_ID = 4; //The ID of the actual contributor of the extension point
+ // Indexes of the various fields
+ private static final byte LABEL = 0; // The human readable name for the extension point
+ private static final byte SCHEMA = 1; // The schema of the extension point
+ private static final byte QUALIFIED_NAME = 2; // The fully qualified name of the extension point
+ private static final byte NAMESPACE = 3; // The name of the namespace of the extension point
+ private static final byte CONTRIBUTOR_ID = 4; // The ID of the actual contributor of the extension point
private static final int EXTRA_SIZE = 5;
protected ExtensionPoint(ExtensionRegistry registry, boolean persist) {
@@ -52,16 +54,20 @@ protected String getSimpleIdentifier() {
}
private String[] getExtraData() {
- //The extension point has been created by parsing, or does not have any extra data
- if (noExtraData()) { //When this is true, the extraInformation is always a String[]. This happens when the object is created by the parser.
+ // The extension point has been created by parsing, or does not have any extra
+ // data
+ if (noExtraData()) { // When this is true, the extraInformation is always a String[]. This happens
+ // when the object is created by the parser.
if (extraInformation != null)
return (String[]) extraInformation;
return new String[EXTRA_SIZE];
}
- //The extension point has been loaded from the cache.
+ // The extension point has been loaded from the cache.
String[] result = null;
- if (extraInformation == null || (result = ((extraInformation instanceof SoftReference) ? (String[]) ((SoftReference>) extraInformation).get() : (String[]) extraInformation)) == null) {
+ if (extraInformation == null || (result = ((extraInformation instanceof SoftReference)
+ ? (String[]) ((SoftReference>) extraInformation).get()
+ : (String[]) extraInformation)) == null) {
result = registry.getTableReader().loadExtensionPointExtraData(getExtraDataOffset());
extraInformation = new SoftReference<>(result);
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointHandle.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointHandle.java
index 1af5cab3e30..ffee72752b0 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointHandle.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointHandle.java
@@ -14,9 +14,9 @@
package org.eclipse.core.internal.registry;
/**
- * The code (minus the getDeclaringPluginDescriptor() was moved into
- * the BaseExtensionPointHandle to avoid duplicating code in the
- * compatibility fragment.
+ * The code (minus the getDeclaringPluginDescriptor() was moved into the
+ * BaseExtensionPointHandle to avoid duplicating code in the compatibility
+ * fragment.
*
* Modifications to the code should be done in the BaseExtensionPointHandle.
*
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointMulti.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointMulti.java
index 49a9b6b2ffa..80ad28ed7f4 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointMulti.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionPointMulti.java
@@ -22,14 +22,15 @@ protected ExtensionPointMulti(ExtensionRegistry registry, boolean persist) {
super(registry, persist);
}
- protected ExtensionPointMulti(int self, int[] children, int dataOffset, ExtensionRegistry registry, boolean persist) {
+ protected ExtensionPointMulti(int self, int[] children, int dataOffset, ExtensionRegistry registry,
+ boolean persist) {
super(self, children, dataOffset, registry, persist);
}
@Override
protected String getLabel(String locale) {
// this method call should be fairly rare, so no caching to save on memory
- String[] translated = registry.translate(new String[] {getLabelAsIs()}, getContributor(), locale);
+ String[] translated = registry.translate(new String[] { getLabelAsIs() }, getContributor(), locale);
return translated[0];
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionRegistry.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionRegistry.java
index cb34de3ac98..dcadbacab2d 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionRegistry.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ExtensionRegistry.java
@@ -49,7 +49,9 @@ public boolean equals(Object another) {
return another instanceof ListenerInfo && ((ListenerInfo) another).listener == this.listener;
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see java.lang.Object#hashCode()
*/
@Override
@@ -61,10 +63,11 @@ public int hashCode() {
// used to enforce concurrent access policy for readers/writers
private final ReadWriteMonitor access = new ReadWriteMonitor();
- // deltas not broadcasted yet. Deltas are kept organized by the namespace name (objects with the same namespace are grouped together)
+ // deltas not broadcasted yet. Deltas are kept organized by the namespace name
+ // (objects with the same namespace are grouped together)
private transient Map
* A corresponding IRegistryChangeEvent will be broadcast to all listeners
* interested on changes in the given plug-in.
@@ -597,7 +640,7 @@ public void remove(String removedContributorId) {
}
}
- //Return the affected namespace
+ // Return the affected namespace
private String removeExtension(int extensionId) {
Extension extension = (Extension) registryObjects.getObject(extensionId, RegistryObjectManager.EXTENSION);
registryObjects.removeExtensionFromNamespaceIndex(extensionId, extension.getNamespaceIdentifier());
@@ -623,7 +666,8 @@ private String removeExtension(int extensionId) {
}
private String removeExtensionPoint(int extPoint) {
- ExtensionPoint extensionPoint = (ExtensionPoint) registryObjects.getObject(extPoint, RegistryObjectManager.EXTENSION_POINT);
+ ExtensionPoint extensionPoint = (ExtensionPoint) registryObjects.getObject(extPoint,
+ RegistryObjectManager.EXTENSION_POINT);
registryObjects.removeExtensionPointFromNamespaceIndex(extPoint, extensionPoint.getNamespace());
int[] existingExtensions = extensionPoint.getRawChildren();
if (existingExtensions != null && existingExtensions.length != 0) {
@@ -680,15 +724,18 @@ public ExtensionRegistry(RegistryStrategy registryStrategy, Object masterToken,
this.userToken = userToken;
registryObjects = new RegistryObjectManager(this);
- boolean isRegistryFilledFromCache = false; // indicates if registry was able to use cache to populate it's content
+ boolean isRegistryFilledFromCache = false; // indicates if registry was able to use cache to populate it's
+ // content
if (strategy.cacheUse()) {
- // Try to read the registry from the cache first. If that fails, create a new registry
+ // Try to read the registry from the cache first. If that fails, create a new
+ // registry
long start = 0;
if (debug())
start = System.currentTimeMillis();
- //The cache is made of several files, find the real names of these other files. If all files are found, try to initialize the objectManager
+ // The cache is made of several files, find the real names of these other files.
+ // If all files are found, try to initialize the objectManager
if (checkCache()) {
try {
theTableReader.setTableFile(cacheStorageManager.lookup(TableReader.TABLE, false));
@@ -703,11 +750,13 @@ public ExtensionRegistry(RegistryStrategy registryStrategy, Object masterToken,
if (isRegistryFilledFromCache)
aggregatedTimestamp.set(timestamp);
} catch (IOException e) {
- // The registry will be rebuilt from the xml files. Make sure to clear anything filled
+ // The registry will be rebuilt from the xml files. Make sure to clear anything
+ // filled
// from cache so that we won't have partially filled items.
isRegistryFilledFromCache = false;
clearRegistryCache();
- log(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, 0, RegistryMessages.registry_bad_cache, e));
+ log(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, 0, RegistryMessages.registry_bad_cache,
+ e));
}
}
@@ -741,16 +790,19 @@ public ExtensionRegistry(RegistryStrategy registryStrategy, Object masterToken,
}
/**
- * Stops the registry. Registry has to be stopped to properly
- * close cache and dispose of listeners.
+ * Stops the registry. Registry has to be stopped to properly close cache and
+ * dispose of listeners.
+ *
* @param key - key token for this registry
*/
@Override
public void stop(Object key) {
// If the registry creator specified a key token, check that the key mathches it
- // (it is assumed that registry owner keeps the key to prevent unautorized accesss).
+ // (it is assumed that registry owner keeps the key to prevent unautorized
+ // accesss).
if (masterToken != null && masterToken != key) {
- throw new IllegalArgumentException("Unauthorized access to the ExtensionRegistry.stop() method. Check if proper access token is supplied."); //$NON-NLS-1$
+ throw new IllegalArgumentException(
+ "Unauthorized access to the ExtensionRegistry.stop() method. Check if proper access token is supplied."); //$NON-NLS-1$
}
// Do extra stop processing if specified in the registry strategy
@@ -801,11 +853,12 @@ public void stop(Object key) {
theTableWriter.setOrphansFile(orphansFile);
} catch (IOException e) {
cacheStorageManager.close();
- return; //Ignore the exception since we can recompute the cache
+ return; // Ignore the exception since we can recompute the cache
}
try {
long timestamp;
- // A bit of backward compatibility: if registry was modified, but timestamp was not,
+ // A bit of backward compatibility: if registry was modified, but timestamp was
+ // not,
// it means that the new timestamp tracking mechanism was not used. In this case
// explicitly obtain timestamps for all contributions. Note that this logic
// maintains a problem described in the bug 104267 for contributions that
@@ -816,34 +869,46 @@ public void stop(Object key) {
timestamp = strategy.getContributionsTimestamp(); // use legacy approach
if (theTableWriter.saveCache(registryObjects, timestamp))
- cacheStorageManager.update(new String[] {TableReader.TABLE, TableReader.MAIN, TableReader.EXTRA, TableReader.CONTRIBUTIONS, TableReader.CONTRIBUTORS, TableReader.NAMESPACES, TableReader.ORPHANS}, new String[] {tableFile.getName(), mainFile.getName(), extraFile.getName(), contributionsFile.getName(), contributorsFile.getName(), namespacesFile.getName(), orphansFile.getName()});
+ cacheStorageManager.update(
+ new String[] { TableReader.TABLE, TableReader.MAIN, TableReader.EXTRA,
+ TableReader.CONTRIBUTIONS, TableReader.CONTRIBUTORS, TableReader.NAMESPACES,
+ TableReader.ORPHANS },
+ new String[] { tableFile.getName(), mainFile.getName(), extraFile.getName(),
+ contributionsFile.getName(), contributorsFile.getName(), namespacesFile.getName(),
+ orphansFile.getName() });
} catch (IOException e) {
- //Ignore the exception since we can recompute the cache
+ // Ignore the exception since we can recompute the cache
}
theTableReader.close();
cacheStorageManager.close();
}
/*
- * Clear the registry cache files from the file manager so on next start-up we recompute it.
+ * Clear the registry cache files from the file manager so on next start-up we
+ * recompute it.
*/
public void clearRegistryCache() {
- for (String key : new String[] {TableReader.TABLE, TableReader.MAIN, TableReader.EXTRA, TableReader.CONTRIBUTIONS, TableReader.ORPHANS})
+ for (String key : new String[] { TableReader.TABLE, TableReader.MAIN, TableReader.EXTRA,
+ TableReader.CONTRIBUTIONS, TableReader.ORPHANS })
try {
cacheStorageManager.remove(key);
} catch (IOException e) {
- log(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, IStatus.ERROR, RegistryMessages.meta_registryCacheReadProblems, e));
+ log(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, IStatus.ERROR,
+ RegistryMessages.meta_registryCacheReadProblems, e));
}
aggregatedTimestamp.reset();
}
/////////////////////////////////////////////////////////////////////////////////////////////////
// Registry Object Factory
- // The factory produces contributions, extension points, extensions, and configuration elements
+ // The factory produces contributions, extension points, extensions, and
+ ///////////////////////////////////////////////////////////////////////////////////////////////// configuration
+ ///////////////////////////////////////////////////////////////////////////////////////////////// elements
// to be stored in the extension registry.
protected RegistryObjectFactory theRegistryObjectFactory = null;
- // Override to provide domain-specific elements to be stored in the extension registry
+ // Override to provide domain-specific elements to be stored in the extension
+ // registry
protected void setElementFactory() {
if (isMultiLanguage)
theRegistryObjectFactory = new RegistryObjectFactoryMulti(this);
@@ -867,9 +932,9 @@ public void log(IStatus status) {
}
/**
- * With multi-locale support enabled this method returns the non-translated
- * key so that they can be cached and translated later into desired languages.
- * In the absence of the multi-locale support the key gets translated immediately
+ * With multi-locale support enabled this method returns the non-translated key
+ * so that they can be cached and translated later into desired languages. In
+ * the absence of the multi-locale support the key gets translated immediately
* and only translated values is cached.
*/
public String translate(String key, ResourceBundle resources) {
@@ -894,7 +959,8 @@ public long computeState() {
return strategy.getContainerTimestamp();
}
- // Find the first location that contains a cache table file and set file manager to it.
+ // Find the first location that contains a cache table file and set file manager
+ // to it.
protected boolean checkCache() {
for (int index = 0; index < strategy.getLocationsLength(); index++) {
File possibleCacheLocation = strategy.getStorage(index);
@@ -907,7 +973,7 @@ protected boolean checkCache() {
try {
cacheFile = cacheStorageManager.lookup(TableReader.getTestFileName(), false);
} catch (IOException e) {
- //Ignore the exception. The registry will be rebuilt from the xml files.
+ // Ignore the exception. The registry will be rebuilt from the xml files.
}
if (cacheFile != null && cacheFile.isFile())
return true; // found the appropriate location
@@ -916,7 +982,8 @@ protected boolean checkCache() {
return false;
}
- public Object createExecutableExtension(RegistryContributor defaultContributor, String className, String requestedContributorName) throws CoreException {
+ public Object createExecutableExtension(RegistryContributor defaultContributor, String className,
+ String requestedContributorName) throws CoreException {
return strategy.createExecutableExtension(defaultContributor, className, requestedContributorName);
}
@@ -927,7 +994,8 @@ public IStatus processChangeEvent(Object[] listenerInfos, final Map
- * If the registry is not modifiable, this method is an access controlled method.
- * Proper token should be passed as an argument for non-modifiable registries.
+ * If the registry is not modifiable, this method is an access controlled
+ * method. Proper token should be passed as an argument for non-modifiable
+ * registries.
*
- * If the registry is not modifiable, this method is an access controlled method.
- * Proper token should be passed as an argument for non-modifiable registries.
+ * If the registry is not modifiable, this method is an access controlled
+ * method. Proper token should be passed as an argument for non-modifiable
+ * registries.
*
+ * Hashtable-based map with integer keys that allows values to be removed by the
+ * garbage collector.
+ *
*
- * When you construct a
+ * When you construct a
*
- * The algorithms used are basically the same as those
- * in {@link java.util.HashMap}. In particular, you
- * can specify a load factor and capacity to suit your
- * needs.
+ * The algorithms used are basically the same as those in
+ * {@link java.util.HashMap}. In particular, you can specify a load factor and
+ * capacity to suit your needs.
*
- * This map does not allow null values. Attempting to add a null
- * value to the map will raise a
+ * This map does not allow null values. Attempting to add a null value to
+ * the map will raise a
*
- * This data structure is not synchronized.
+ * This data structure is not synchronized.
*
- * @see java.lang.ref.Reference
+ * @see java.lang.ref.Reference
*/
public class ReferenceMap {
/**
- * IEntry implementation that acts as a hard reference.
- * The value of a hard reference entry is never garbage
- * collected until it is explicitly removed from the map.
+ * IEntry implementation that acts as a hard reference. The value of a hard
+ * reference entry is never garbage collected until it is explicitly removed
+ * from the map.
*/
private static class HardRef implements IEntry {
private final int key;
private IEntry next;
/**
- * Reference value. Note this can never be null.
+ * Reference value. Note this can never be null.
*/
private final Object value;
@@ -98,33 +97,35 @@ public String toString() {
}
/**
- * The common interface for all elements in the map. Both
- * hard and soft map values conform to this interface.
+ * The common interface for all elements in the map. Both hard and soft map
+ * values conform to this interface.
*/
private static interface IEntry {
/**
* Returns the integer key for this entry.
+ *
* @return The integer key
*/
public int getKey();
/**
- * Returns the next entry in the linked list of entries
- * with the same hash value, or
+ * true
the plugin providing the
- * factory will be loaded if necessary, otherwise no plugin activations
- * will occur.
+ * Loads the real adapter factory, but only if its associated plug-in is already
+ * loaded. Returns the real factory if it was successfully loaded.
+ *
+ * @param force if true
the plugin providing the factory will be
+ * loaded if necessary, otherwise no plugin activations will occur.
*/
@Override
public synchronized IAdapterFactory loadFactory(boolean force) {
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterManagerListener.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterManagerListener.java
index d57cbe76e10..f7436a48283 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterManagerListener.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/adapter/AdapterManagerListener.java
@@ -36,9 +36,9 @@ public AdapterManagerListener() {
}
/**
- * Loads adapters registered with the adapters extension point from
- * the plug-in registry. Note that the actual factory implementations
- * are loaded lazily as they are needed.
+ * Loads adapters registered with the adapters extension point from the plug-in
+ * registry. Note that the actual factory implementations are loaded lazily as
+ * they are needed.
*/
@Override
public boolean addFactories(AdapterManager adapterManager) {
@@ -84,7 +84,8 @@ public synchronized void removed(IExtension[] extensions) {
theAdapterManager.flushLookup();
for (IExtension extension : extensions) {
for (Listtrue
if successful, false
if a problem was encountered
+ *
+ * @param identifier Id of the extension point. If non-qualified names is
+ * supplied, it will be converted internally into a fully
+ * qualified name
+ * @param contributor the contributor of this extension point
+ * @param persist indicates if contribution should be stored in the
+ * registry cache. If false, contribution is not
+ * persisted in the registry cache and is lost on Eclipse
+ * restart
+ * @param label display string for the extension point
+ * @param schemaReference reference to the extension point schema. The schema
+ * reference is a URL path relative to the plug-in
+ * installation URL. May be null
+ * @param token the key used to check permissions. Two registry keys
+ * are set in the registry constructor
+ * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
+ * master token and a user token. Master token allows all
+ * operations; user token allows non-persisted registry
+ * elements to be modified.
+ * @return true
if successful, false
if a problem was
+ * encountered
* @throws IllegalArgumentException if incorrect token is passed in
*/
- public boolean addExtensionPoint(String identifier, IContributor contributor, boolean persist, String label, String schemaReference, Object token) throws IllegalArgumentException {
+ public boolean addExtensionPoint(String identifier, IContributor contributor, boolean persist, String label,
+ String schemaReference, Object token) throws IllegalArgumentException {
if (!checkReadWriteAccess(token, persist))
- throw new IllegalArgumentException("Unauthorized access to the ExtensionRegistry.addExtensionPoint() method. Check if proper access token is supplied."); //$NON-NLS-1$
+ throw new IllegalArgumentException(
+ "Unauthorized access to the ExtensionRegistry.addExtensionPoint() method. Check if proper access token is supplied."); //$NON-NLS-1$
RegistryContributor internalContributor = (RegistryContributor) contributor;
registryObjects.addContributor(internalContributor); // only adds a contributor if it is not already present
@@ -1164,7 +1250,8 @@ public boolean addExtensionPoint(String identifier, IContributor contributor, bo
if (!getObjectManager().addExtensionPoint(currentExtPoint, true)) {
if (debug()) {
- String msg = NLS.bind(RegistryMessages.parse_duplicateExtensionPoint, uniqueId, contribution.getDefaultNamespace());
+ String msg = NLS.bind(RegistryMessages.parse_duplicateExtensionPoint, uniqueId,
+ contribution.getDefaultNamespace());
log(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, 0, msg, null));
}
return false;
@@ -1172,7 +1259,8 @@ public boolean addExtensionPoint(String identifier, IContributor contributor, bo
currentExtPoint.setContributorId(contributorId);
- // array format: {Number of extension points, Number of extensions, Extension Id}
+ // array format: {Number of extension points, Number of extensions, Extension
+ // Id}
int[] contributionChildren = new int[3];
// Put the extension points into this namespace
contributionChildren[Contribution.EXTENSION_POINT] = 1;
@@ -1188,30 +1276,42 @@ public boolean addExtensionPoint(String identifier, IContributor contributor, bo
/**
* Adds an extension to the extension registry.
* true
if successful, false
if a problem was encountered
+ * @param token the key used to check permissions. Two registry
+ * keys are set in the registry constructor
+ * {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
+ * master token and a user token. Master token
+ * allows all operations; user token allows
+ * non-persisted registry elements to be modified.
+ * @return true
if successful, false
if a problem was
+ * encountered
* @throws IllegalArgumentException if incorrect token is passed in
*/
- public boolean addExtension(String identifier, IContributor contributor, boolean persist, String label, String extensionPointId, ConfigurationElementDescription configurationElements, Object token) throws IllegalArgumentException {
+ public boolean addExtension(String identifier, IContributor contributor, boolean persist, String label,
+ String extensionPointId, ConfigurationElementDescription configurationElements, Object token)
+ throws IllegalArgumentException {
if (!checkReadWriteAccess(token, persist))
- throw new IllegalArgumentException("Unauthorized access to the ExtensionRegistry.addExtensionPoint() method. Check if proper access token is supplied."); //$NON-NLS-1$
+ throw new IllegalArgumentException(
+ "Unauthorized access to the ExtensionRegistry.addExtensionPoint() method. Check if proper access token is supplied."); //$NON-NLS-1$
// prepare namespace information
RegistryContributor internalContributor = (RegistryContributor) contributor;
registryObjects.addContributor(internalContributor); // only adds a contributor if it is not already present
@@ -1244,7 +1344,8 @@ public boolean addExtension(String identifier, IContributor contributor, boolean
targetExtensionPointId = extensionPointId;
currentExtension.setExtensionPointIdentifier(targetExtensionPointId);
- // if we have an Id specified, check for duplicates. Only issue warning if duplicate found
+ // if we have an Id specified, check for duplicates. Only issue warning if
+ // duplicate found
// as it might still work fine - depending on the access pattern.
if (simpleId != null && debug()) {
String uniqueId = namespaceName + '.' + simpleId;
@@ -1252,7 +1353,8 @@ public boolean addExtension(String identifier, IContributor contributor, boolean
if (existingExtension != null) {
String currentSupplier = contribution.getDefaultNamespace();
String existingSupplier = existingExtension.getContributor().getName();
- String msg = NLS.bind(RegistryMessages.parse_duplicateExtension, new String[] {currentSupplier, existingSupplier, uniqueId});
+ String msg = NLS.bind(RegistryMessages.parse_duplicateExtension,
+ new String[] { currentSupplier, existingSupplier, uniqueId });
log(new Status(IStatus.WARNING, RegistryMessages.OWNER_NAME, 0, msg, null));
return false;
}
@@ -1276,7 +1378,8 @@ public boolean addExtension(String identifier, IContributor contributor, boolean
}
// Fill in the actual content of this extension
- private void createExtensionData(String contributorId, ConfigurationElementDescription description, RegistryObject parent, boolean persist) {
+ private void createExtensionData(String contributorId, ConfigurationElementDescription description,
+ RegistryObject parent, boolean persist) {
ConfigurationElement currentConfigurationElement = getElementFactory().createConfigurationElement(persist);
currentConfigurationElement.setContributorId(contributorId);
currentConfigurationElement.setName(description.getName());
@@ -1317,7 +1420,9 @@ private void createExtensionData(String contributorId, ConfigurationElementDescr
newValues[size] = currentConfigurationElement.getObjectId();
parent.setRawChildren(newValues);
currentConfigurationElement.setParentId(parent.getObjectId());
- currentConfigurationElement.setParentType(parent instanceof ConfigurationElement ? RegistryObjectManager.CONFIGURATION_ELEMENT : RegistryObjectManager.EXTENSION);
+ currentConfigurationElement
+ .setParentType(parent instanceof ConfigurationElement ? RegistryObjectManager.CONFIGURATION_ELEMENT
+ : RegistryObjectManager.EXTENSION);
}
@Override
@@ -1336,7 +1441,8 @@ public boolean removeExtensionPoint(IExtensionPoint extensionPoint, Object token
private boolean removeObject(RegistryObject registryObject, boolean isExtensionPoint, Object token) {
if (!checkReadWriteAccess(token, registryObject.shouldPersist()))
- throw new IllegalArgumentException("Unauthorized access to the ExtensionRegistry.removeExtension() method. Check if proper access token is supplied."); //$NON-NLS-1$
+ throw new IllegalArgumentException(
+ "Unauthorized access to the ExtensionRegistry.removeExtension() method. Check if proper access token is supplied."); //$NON-NLS-1$
int id = registryObject.getObjectId();
access.enterWrite();
@@ -1349,8 +1455,10 @@ private boolean removeObject(RegistryObject registryObject, boolean isExtensionP
namespace = removeExtension(id);
MapgetStatus()
.
+ * Handles an error state specified by the status. The collection of all logged
+ * status objects can be accessed using getStatus()
.
*
* @param error a status detailing the error condition
*/
@@ -687,11 +735,13 @@ protected String translate(String key) {
}
/**
- * Fixes up the extension declarations in the given pre-3.0 plug-in or fragment to compensate
- * for extension points that were renamed between release 2.1 and 3.0.
+ * Fixes up the extension declarations in the given pre-3.0 plug-in or fragment
+ * to compensate for extension points that were renamed between release 2.1 and
+ * 3.0.
*/
private Extension[] fixRenamedExtensionPoints(Extension[] extensions) {
- if (extensions == null || versionAtLeast(VERSION_3_0) || RegistryProperties.getProperty(NO_EXTENSION_MUNGING) != null)
+ if (extensions == null || versionAtLeast(VERSION_3_0)
+ || RegistryProperties.getProperty(NO_EXTENSION_MUNGING) != null)
return extensions;
for (Extension extension : extensions) {
String oldPointId = extension.getExtensionPointIdentifier();
@@ -704,17 +754,18 @@ private Extension[] fixRenamedExtensionPoints(Extension[] extensions) {
}
/**
- * To preserve backward compatibility, we will only attempt to extract namespace form the name
- * if Eclipse version specified in the plugin.xml () is at least 3.2.
+ * To preserve backward compatibility, we will only attempt to extract namespace
+ * form the name if Eclipse version specified in the plugin.xml () is at least 3.2.
*/
private void initializeExtractNamespace() {
extractNamespaces = Boolean.valueOf(versionAtLeast(VERSION_3_2)).booleanValue();
}
/**
- * Makes sense only for plugin.xml versions >= 3.0 (Eclipse version was introduced in 3.0).
- * Assumes that version is stored as "X1.X2.....XN" where X1 is a major version; X2 is a minor version
- * and so on.
+ * Makes sense only for plugin.xml versions >= 3.0 (Eclipse version was
+ * introduced in 3.0). Assumes that version is stored as "X1.X2.....XN" where X1
+ * is a major version; X2 is a minor version and so on.
*/
private boolean versionAtLeast(String testVersion) {
if (schemaVersion == null)
@@ -724,7 +775,8 @@ private boolean versionAtLeast(String testVersion) {
StringTokenizer schemaVersionTokenizer = new StringTokenizer(schemaVersion, "."); //$NON-NLS-1$
while (testVersionTokenizer.hasMoreTokens() && schemaVersionTokenizer.hasMoreTokens()) {
try {
- if (Integer.parseInt(schemaVersionTokenizer.nextToken()) < Integer.parseInt(testVersionTokenizer.nextToken()))
+ if (Integer.parseInt(schemaVersionTokenizer.nextToken()) < Integer
+ .parseInt(testVersionTokenizer.nextToken()))
return false;
} catch (NumberFormatException e) {
return false;
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Handle.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Handle.java
index 93e8f07365d..a7c20e4682e 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Handle.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/Handle.java
@@ -16,9 +16,11 @@
import org.eclipse.core.runtime.InvalidRegistryObjectException;
/**
- * A handle is the super class to all registry objects that are now served to users.
- * The handles never hold on to any "real" content of the object being represented.
- * A handle can become stale if its referenced object has been removed from the registry.
+ * A handle is the super class to all registry objects that are now served to
+ * users. The handles never hold on to any "real" content of the object being
+ * represented. A handle can become stale if its referenced object has been
+ * removed from the registry.
+ *
* @since 3.1.
*/
public abstract class Handle {
@@ -37,6 +39,7 @@ public int getId() {
/**
* Return the actual object corresponding to this handle.
+ *
* @throws InvalidRegistryObjectException when the handle is stale.
*/
abstract RegistryObject getObject();
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/HashtableOfStringAndInt.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/HashtableOfStringAndInt.java
index b8f8dc6e0d9..93c1830161f 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/HashtableOfStringAndInt.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/HashtableOfStringAndInt.java
@@ -46,18 +46,18 @@ public HashtableOfStringAndInt(int size) {
@Override
public Object clone() throws CloneNotSupportedException {
throw new CloneNotSupportedException();
- // HashtableOfStringAndInt result = (HashtableOfStringAndInt) super.clone();
- // result.elementSize = this.elementSize;
- // result.threshold = this.threshold;
+ // HashtableOfStringAndInt result = (HashtableOfStringAndInt) super.clone();
+ // result.elementSize = this.elementSize;
+ // result.threshold = this.threshold;
//
- // int length = this.keyTable.length;
- // result.keyTable = new char[length][];
- // System.arraycopy(this.keyTable, 0, result.keyTable, 0, length);
+ // int length = this.keyTable.length;
+ // result.keyTable = new char[length][];
+ // System.arraycopy(this.keyTable, 0, result.keyTable, 0, length);
//
- // length = this.valueTable.length;
- // result.valueTable = new Object[length];
- // System.arraycopy(this.valueTable, 0, result.valueTable, 0, length);
- // return result;
+ // length = this.valueTable.length;
+ // result.valueTable = new Object[length];
+ // System.arraycopy(this.valueTable, 0, result.valueTable, 0, length);
+ // return result;
}
public boolean containsKey(String key) {
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/IRegistryConstants.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/IRegistryConstants.java
index 5bd71f71392..0559ee2ac7e 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/IRegistryConstants.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/IRegistryConstants.java
@@ -16,8 +16,9 @@
public interface IRegistryConstants {
/**
- * The unique identifier constant (value "org.eclipse.core.runtime
")
- * of the Core Runtime (pseudo-) plug-in.
+ * The unique identifier constant (value
+ * "org.eclipse.core.runtime
") of the Core Runtime (pseudo-)
+ * plug-in.
*/
public static final String RUNTIME_NAME = "org.eclipse.core.runtime"; //$NON-NLS-1$
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/KeyedHashSet.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/KeyedHashSet.java
index 2377703b57d..e75850e04ab 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/KeyedHashSet.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/KeyedHashSet.java
@@ -15,8 +15,8 @@
/**
* Note this is a copy of a data structure from OSGi, package
- * org.eclipse.osgi.framework.internal.core. Unused methods were removed
- * from this copy.
+ * org.eclipse.osgi.framework.internal.core. Unused methods were removed from
+ * this copy.
*/
public class KeyedHashSet {
protected static final int MINIMUM_SIZE = 7;
@@ -42,6 +42,7 @@ public KeyedHashSet(int capacity, boolean replace) {
/**
* Adds an element to this set. If an element with the same key already exists,
* replaces it depending on the replace flag.
+ *
* @return true if the element was added/stored, false otherwise
*/
public boolean add(KeyedElement element) {
@@ -105,8 +106,8 @@ public Object[] elements(Object[] result) {
}
/**
- * The array isn't large enough so double its size and rehash
- * all its current values.
+ * The array isn't large enough so double its size and rehash all its current
+ * values.
*/
protected void expand() {
KeyedElement[] oldElements = elements;
@@ -127,8 +128,7 @@ protected void expand() {
}
/**
- * Returns the set element with the given id, or null
- * if not found.
+ * Returns the set element with the given id, or null if not found.
*/
public KeyedElement get(KeyedElement key) {
if (elementCount == 0)
@@ -158,8 +158,7 @@ public KeyedElement get(KeyedElement key) {
}
/**
- * Returns the set element with the given id, or null
- * if not found.
+ * Returns the set element with the given id, or null if not found.
*/
public KeyedElement getByKey(Object key) {
if (elementCount == 0)
@@ -201,8 +200,8 @@ private int keyHash(Object key) {
}
/**
- * The element at the given index has been removed so move
- * elements to keep the set properly hashed.
+ * The element at the given index has been removed so move elements to keep the
+ * set properly hashed.
*/
protected void rehashTo(int anIndex) {
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/OffsetTable.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/OffsetTable.java
index 3f8a0c41f0e..99001680d7b 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/OffsetTable.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/OffsetTable.java
@@ -16,8 +16,8 @@
import java.io.*;
/**
- * This table stores file offsets for cached registry objects.
- * Entries are never added when this table resides in memory. Entries could be removed.
+ * This table stores file offsets for cached registry objects. Entries are never
+ * added when this table resides in memory. Entries could be removed.
*/
public final class OffsetTable {
@@ -36,12 +36,14 @@ public int get(int key) {
}
public void removeKey(int key) {
- if (key < valueTable.length) // registry elements added in the running session will have IDs outside of the valid offset range
+ if (key < valueTable.length) // registry elements added in the running session will have IDs outside of the
+ // valid offset range
valueTable[key] = Integer.MIN_VALUE;
}
public void put(int key, int value) {
- if (key >= valueTable.length) { // this should not happen in the expected use cases as we know the max size in advance
+ if (key >= valueTable.length) { // this should not happen in the expected use cases as we know the max size in
+ // advance
int[] newTable = new int[(int) (key * GROWTH_FACTOR)];
System.arraycopy(valueTable, 0, newTable, 0, valueTable.length);
valueTable = newTable;
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReadWriteMonitor.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReadWriteMonitor.java
index b564650e8cc..994084cc640 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReadWriteMonitor.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReadWriteMonitor.java
@@ -14,25 +14,23 @@
package org.eclipse.core.internal.registry;
/**
- * Monitor ensuring no more than one writer working concurrently.
- * Multiple readers are allowed to perform simultaneously.
+ * Monitor ensuring no more than one writer working concurrently. Multiple
+ * readers are allowed to perform simultaneously.
*
* This class was borrowed from org.eclipse.jdt.internal.core.search.indexing.
*/
public class ReadWriteMonitor {
/**
- * <0 : writing (cannot go beyond -1, i.e one concurrent writer)
- * =0 : idle
- * >0 : reading (number of concurrent readers)
+ * <0 : writing (cannot go beyond -1, i.e one concurrent writer) =0 : idle >0 :
+ * reading (number of concurrent readers)
*/
private int status = 0;
private Thread writeLockowner;
/**
- * Concurrent reading is allowed
- * Blocking only when already writing.
+ * Concurrent reading is allowed Blocking only when already writing.
*/
public synchronized void enterRead() {
if (writeLockowner == Thread.currentThread())
@@ -48,8 +46,8 @@ public synchronized void enterRead() {
}
/**
- * Only one writer at a time is allowed to perform
- * Blocking only when already writing or reading.
+ * Only one writer at a time is allowed to perform Blocking only when already
+ * writing or reading.
*/
public synchronized void enterWrite() {
if (writeLockowner != Thread.currentThread()) {
@@ -77,14 +75,14 @@ public synchronized void exitRead() {
}
/**
- * When writing is over, all readers and possible
- * writers are granted permission to restart concurrently
+ * When writing is over, all readers and possible writers are granted permission
+ * to restart concurrently
*/
public synchronized void exitWrite() {
if (writeLockowner != Thread.currentThread())
throw new IllegalStateException("Current owner is " + writeLockowner); //$NON-NLS-1$
if (++status == 0) {
- // System.out.println(this + "exitWrite:" + Thread.currentThread());
+ // System.out.println(this + "exitWrite:" + Thread.currentThread());
writeLockowner = null;
notifyAll();
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReferenceMap.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReferenceMap.java
index 79eeccfabc8..2130723d2b9 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReferenceMap.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/ReferenceMap.java
@@ -25,43 +25,42 @@
import java.lang.ref.*;
/**
- * Hashtable-based map with integer keys that allows values to be removed
- * by the garbage collector.ReferenceMap
, you can
- * specify what kind of references are used to store the
- * map's values. If non-hard references are
- * used, then the garbage collector can remove mappings
- * if a value becomes unreachable, or if the
- * JVM's memory is running low. For information on how
- * the different reference types behave, see
- * {@link Reference}.ReferenceMap
, you can specify what kind of
+ * references are used to store the map's values. If non-hard references are
+ * used, then the garbage collector can remove mappings if a value becomes
+ * unreachable, or if the JVM's memory is running low. For information on how
+ * the different reference types behave, see {@link Reference}.
+ * NullPointerException
.NullPointerException
.
+ * null
- * if there is no next entry.
+ * Returns the next entry in the linked list of entries with the same hash
+ * value, or null
if there is no next entry.
+ *
* @return The next entry, or null
.
*/
public IEntry getNext();
/**
* Returns the value of this entry.
+ *
* @return The entry value.
*/
public Object getValue();
/**
- * Sets the next entry in the linked list of map entries
- * with the same hash value.
+ * Sets the next entry in the linked list of map entries with the same hash
+ * value.
*
* @param next The next entry, or null
.
*/
@@ -132,8 +133,8 @@ private static interface IEntry {
}
/**
- * Augments a normal soft reference with additional information
- * required to implement the IEntry interface.
+ * Augments a normal soft reference with additional information required to
+ * implement the IEntry interface.
*/
private static class SoftRef extends SoftReference
+ * The registry strategy that can be used in OSGi world. It provides the
+ * following functionality:
+ *
*
* It is expected that both attribute name and attribute value are not null. *
@@ -27,6 +28,7 @@ ** This class is not intended to be subclassed. *
+ * * @see ConfigurationElementDescription * @see IConfigurationElement */ @@ -34,12 +36,14 @@ public final class ConfigurationElementAttribute { /** * Attribute name. + * * @see IConfigurationElement#getAttributeNames() */ private String name; /** * Attribute value. + * * @see IConfigurationElement#getAttributeAsIs(String) */ private String value; @@ -47,7 +51,7 @@ public final class ConfigurationElementAttribute { /** * Constructor. * - * @param name attribute name + * @param name attribute name * @param value attribute value */ public ConfigurationElementAttribute(String name, String value) { @@ -57,6 +61,7 @@ public ConfigurationElementAttribute(String name, String value) { /** * Returns attribute name. + * * @return attribute name * @see IConfigurationElement#getAttributeNames() */ @@ -66,6 +71,7 @@ public String getName() { /** * Returns value of the attribute. + * * @return attribute value * @see IConfigurationElement#getAttributeAsIs(String) */ diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/spi/ConfigurationElementDescription.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/spi/ConfigurationElementDescription.java index 202b1eb3213..c24b92cbbc8 100644 --- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/spi/ConfigurationElementDescription.java +++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/internal/registry/spi/ConfigurationElementDescription.java @@ -16,13 +16,14 @@ import org.eclipse.core.runtime.IConfigurationElement; /** - * Describes configuration elements (content of an extension) to be added to - * the extension registry. Configuration element can contain attributes or - * a String value. Configuration element can contain other configuration - * elements (children). + * Describes configuration elements (content of an extension) to be added to the + * extension registry. Configuration element can contain attributes or a String + * value. Configuration element can contain other configuration elements + * (children). ** It is expected that configuration element's name is not null. Attributes and - * children of the extension description might be null; value might be null as well. + * children of the extension description might be null; value might be null as + * well. *
** This class can be instantiated. @@ -30,30 +31,35 @@ *
* This class is not intended to be subclassed. *
+ * * @see ConfigurationElementAttribute */ public final class ConfigurationElementDescription { /** * Name of the configuration element. + * * @see IConfigurationElement#getName() */ private String name; /** * Attributes of the configuration element. + * * @see IConfigurationElement#getAttribute(String) */ private ConfigurationElementAttribute[] attributes; /** * String value to be stored in this configuration element. + * * @see IConfigurationElement#getValue() */ private String value; /** * Children of the configuration element. + * * @see IConfigurationElement#getChildren() */ private ConfigurationElementDescription[] children; @@ -61,16 +67,17 @@ public final class ConfigurationElementDescription { /** * Constructor. * - * @param name - name of the configuration element + * @param name - name of the configuration element * @param attributes - attributes of the configuration element. Might be null. - * @param value - string value to be stored. Might be null. - * @param children - children of the configuration element. Might be null. + * @param value - string value to be stored. Might be null. + * @param children - children of the configuration element. Might be null. * @see IConfigurationElement#getName() * @see IConfigurationElement#getChildren() * @see IConfigurationElement#getAttribute(String) * @see IConfigurationElement#getValue() */ - public ConfigurationElementDescription(String name, ConfigurationElementAttribute[] attributes, String value, ConfigurationElementDescription[] children) { + public ConfigurationElementDescription(String name, ConfigurationElementAttribute[] attributes, String value, + ConfigurationElementDescription[] children) { this.name = name; this.attributes = attributes; this.value = value; @@ -80,24 +87,26 @@ public ConfigurationElementDescription(String name, ConfigurationElementAttribut /** * Constructor. * - * @param name - name of the configuration element + * @param name - name of the configuration element * @param attribute - attribute of the configuration element. Might be null. - * @param value - string value to be stored. Might be null. - * @param children - children of the configuration element. Might be null. + * @param value - string value to be stored. Might be null. + * @param children - children of the configuration element. Might be null. * @see IConfigurationElement#getName() * @see IConfigurationElement#getChildren() * @see IConfigurationElement#getAttribute(String) * @see IConfigurationElement#getValue() */ - public ConfigurationElementDescription(String name, ConfigurationElementAttribute attribute, String value, ConfigurationElementDescription[] children) { + public ConfigurationElementDescription(String name, ConfigurationElementAttribute attribute, String value, + ConfigurationElementDescription[] children) { this.name = name; - this.attributes = new ConfigurationElementAttribute[] {attribute}; + this.attributes = new ConfigurationElementAttribute[] { attribute }; this.value = value; this.children = children; } /** * Returns children of the configuration element. + * * @return - children of the extension * @see IConfigurationElement#getChildren() */ @@ -107,6 +116,7 @@ public ConfigurationElementDescription[] getChildren() { /** * Returns name of the configuration element. + * * @return - extension name * @see IConfigurationElement#getName() */ @@ -116,6 +126,7 @@ public String getName() { /** * Returns attributes of the configuration element. + * * @return - attributes of the extension description * @see IConfigurationElement#getAttribute(String) */ @@ -125,6 +136,7 @@ public ConfigurationElementAttribute[] getAttributes() { /** * Returns string value stored in the configuration element. + * * @return - String value to be stored in the element * @see IConfigurationElement#getValue() */ diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactoryOSGi.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactoryOSGi.java index 0f5235eaeb3..df722c1ecb9 100644 --- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactoryOSGi.java +++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactoryOSGi.java @@ -18,11 +18,12 @@ import org.osgi.framework.Bundle; /** - * The contributor factory creates new registry contributors for use in OSGi-based - * registries. + * The contributor factory creates new registry contributors for use in + * OSGi-based registries. ** This class can not be extended or instantiated by clients. *
+ * * @since org.eclipse.equinox.registry 3.2 * @noinstantiate This class is not intended to be instantiated by clients. * @noextend This class is not intended to be subclassed by clients. @@ -30,8 +31,8 @@ public final class ContributorFactoryOSGi { /** - * Creates registry contributor object based on a Bundle. The bundle must not - * benull
.
+ * Creates registry contributor object based on a Bundle. The bundle must not be
+ * null
.
*
* @param contributor bundle associated with the contribution
* @return new registry contributor based on the Bundle
@@ -56,12 +57,14 @@ public static IContributor createContributor(Bundle contributor) {
}
/**
- * Returns the OSGi bundle used to define this contributor. If a fragment
- * was used to create the contributor, the fragment is returned.
+ * Returns the OSGi bundle used to define this contributor. If a fragment was
+ * used to create the contributor, the fragment is returned.
*
- * The method may return null if the contributor is not based on a bundle, - * if the bundle can't be found, or if the bundle is presently unresolved or - * uninstalled.
+ *+ * The method may return null if the contributor is not based on a bundle, if + * the bundle can't be found, or if the bundle is presently unresolved or + * uninstalled. + *
* * @param contributor bundle-based registry contributor * @return the actual OSGi bundle associated with this contributor diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactorySimple.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactorySimple.java index 495e119a330..e55b985f916 100644 --- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactorySimple.java +++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/ContributorFactorySimple.java @@ -20,9 +20,11 @@ * registry based on the String representation of the determining object. ** This class can be used without OSGi running. - *
+ *
+ ** This class can not be extended or instantiated by clients. *
+ * * @since org.eclipse.equinox.registry 3.2 * @noinstantiate This class is not intended to be instantiated by clients. * @noextend This class is not intended to be subclassed by clients. @@ -30,8 +32,8 @@ public final class ContributorFactorySimple { /** - * Creates registry contributor object based on a determining object.The determining - * object must not benull
.
+ * Creates registry contributor object based on a determining object.The
+ * determining object must not be null
.
*
* @param determiningObject object associated with the contribution
* @return new registry contributor based on the determining object
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IConfigurationElement.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IConfigurationElement.java
index bd138707400..c9a49948e2e 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IConfigurationElement.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IConfigurationElement.java
@@ -14,72 +14,79 @@
package org.eclipse.core.runtime;
/**
- * A configuration element, with its attributes and children,
- * directly reflects the content and structure of the extension section
- * within the declaring plug-in's manifest (plugin.xml
) file.
+ * A configuration element, with its attributes and children, directly reflects
+ * the content and structure of the extension section within the declaring
+ * plug-in's manifest (plugin.xml
) file.
* - * This interface also provides a way to create executable extension - * objects. + * This interface also provides a way to create executable extension objects. *
*
- * These registry objects are intended for relatively short-term use. Clients that
- * deal with these objects must be aware that they may become invalid if the
- * declaring plug-in is updated or uninstalled. If this happens, all methods except
- * {@link #isValid()} will throw {@link InvalidRegistryObjectException}.
- * For configuration element objects, the most common case is code in a plug-in dealing
- * with extensions contributed to one of the extension points it declares.
- * Code in a plug-in that has declared that it is not dynamic aware (or not
- * declared anything) can safely ignore this issue, since the registry
+ * These registry objects are intended for relatively short-term use. Clients
+ * that deal with these objects must be aware that they may become invalid if
+ * the declaring plug-in is updated or uninstalled. If this happens, all methods
+ * except {@link #isValid()} will throw {@link InvalidRegistryObjectException}.
+ * For configuration element objects, the most common case is code in a plug-in
+ * dealing with extensions contributed to one of the extension points it
+ * declares. Code in a plug-in that has declared that it is not dynamic aware
+ * (or not declared anything) can safely ignore this issue, since the registry
* would not be modified while it is active. However, code in a plug-in that
- * declares that it is dynamic aware must be careful when accessing the extension
- * and configuration element objects because they become invalid if the contributing
- * plug-in is removed. Similarly, tools that analyze or display the extension registry
- * are vulnerable. Client code can pre-test for invalid objects by calling {@link #isValid()},
- * which never throws this exception. However, pre-tests are usually not sufficient
- * because of the possibility of the extension or configuration element object becoming
- * invalid as a result of a concurrent activity. At-risk clients must treat
- * InvalidRegistryObjectException
as if it were a checked exception.
- * Also, such clients should probably register a listener with the extension registry
- * so that they receive notification of any changes to the registry.
- *
+ * declares that it is dynamic aware must be careful when accessing the
+ * extension and configuration element objects because they become invalid if
+ * the contributing plug-in is removed. Similarly, tools that analyze or display
+ * the extension registry are vulnerable. Client code can pre-test for invalid
+ * objects by calling {@link #isValid()}, which never throws this exception.
+ * However, pre-tests are usually not sufficient because of the possibility of
+ * the extension or configuration element object becoming invalid as a result of
+ * a concurrent activity. At-risk clients must treat
+ * InvalidRegistryObjectException
as if it were a checked
+ * exception. Also, such clients should probably register a listener with the
+ * extension registry so that they receive notification of any changes to the
+ * registry.
+ *
* This interface can be used without OSGi running. - *
+ *
+ ** This interface is not intended to be implemented by clients. *
+ * * @noimplement This interface is not intended to be implemented by clients. */ public interface IConfigurationElement { /** - * Creates and returns a new instance of the executable extension - * identified by the named attribute of this configuration element. - * The named attribute value must contain a fully qualified name - * of a Java class. The class can either refer to a class implementing - * the executable extension or to a factory capable of returning the - * executable extension. + * Creates and returns a new instance of the executable extension identified by + * the named attribute of this configuration element. The named attribute value + * must contain a fully qualified name of a Java class. The class can either + * refer to a class implementing the executable extension or to a factory + * capable of returning the executable extension. ** The specified class is instantiated using its 0-argument public constructor. *
* Then the following checks are done:
- * If the specified class implements the {@link IExecutableExtension}
- * interface, the method {@link IExecutableExtension#setInitializationData(IConfigurationElement, String, Object)}
- * is called, passing to the object the configuration information that was used to create it.
+ * If the specified class implements the {@link IExecutableExtension} interface,
+ * the method
+ * {@link IExecutableExtension#setInitializationData(IConfigurationElement, String, Object)}
+ * is called, passing to the object the configuration information that was used
+ * to create it.
*
* If the specified class implements {@link IExecutableExtensionFactory} - * interface, the method {@link IExecutableExtensionFactory#create()} - * is invoked. + * interface, the method {@link IExecutableExtensionFactory#create()} is + * invoked. *
*- * Unlike other methods on this object, invoking this method may activate - * the plug-in. + * Unlike other methods on this object, invoking this method may activate the + * plug-in. *
* * @param propertyName the name of the property * @return the executable instance - * @exception CoreException if an instance of the executable extension - * could not be created for any reason - * @see IExecutableExtension#setInitializationData(IConfigurationElement, String, Object) + * @exception CoreException if an instance of the executable extension could not + * be created for any reason + * @see IExecutableExtension#setInitializationData(IConfigurationElement, + * String, Object) * @see IExecutableExtensionFactory - * @throws InvalidRegistryObjectException if this configuration element is no longer valid + * @throws InvalidRegistryObjectException if this configuration element is no + * longer valid */ public Object createExecutableExtension(String propertyName) throws CoreException; @@ -87,42 +94,49 @@ public interface IConfigurationElement { * Returns the named attribute of this configuration element, or *null
if none.
* - * The names of configuration element attributes - * are the same as the attribute names of the corresponding XML element. - * For example, the configuration markup
+ * The names of configuration element attributes are the same as the attribute + * names of the corresponding XML element. For example, the configuration markup + * + * ** <bg pattern="stripes"/> **
- * corresponds to a configuration element named "bg"
- * with an attribute named "pattern"
- * with attribute value "stripes"
.
+ * corresponds to a configuration element named "bg"
with an
+ * attribute named "pattern"
with attribute value
+ * "stripes"
.
*
Note that any translation specified in the plug-in manifest - * file is automatically applied. + *
+ * Note that any translation specified in the plug-in manifest file is + * automatically applied. *
* * @param name the name of the attribute * @return attribute value, ornull
if none
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
*/
public String getAttribute(String name) throws InvalidRegistryObjectException;
/**
- * When multi-language support is enabled, this method returns the named attribute of this
- * configuration element in the specified locale, or null
if none.
+ * When multi-language support is enabled, this method returns the named
+ * attribute of this configuration element in the specified locale, or
+ * null
if none.
* - * The locale matching tries to find the best match between available translations and - * the requested locale, falling back to a more generic locale ("en") when the specific - * locale ("en_US") is not available. - *
- * If multi-language support is not enabled, this method is equivalent to the method - * {@link #getAttribute(String)}. + * The locale matching tries to find the best match between available + * translations and the requested locale, falling back to a more generic locale + * ("en") when the specific locale ("en_US") is not available. *
+ *+ * If multi-language support is not enabled, this method is equivalent to the + * method {@link #getAttribute(String)}. + *
+ * * @param attrName the name of the attribute - * @param locale the requested locale + * @param locale the requested locale * @return attribute value, ornull
if none
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
* @see #getAttribute(String)
* @see IExtensionRegistry#isMultiLanguage()
* @since org.eclipse.equinox.registry 3.5
@@ -133,60 +147,65 @@ public interface IConfigurationElement {
* Returns the named attribute of this configuration element, or
* null
if none.
* - * The names of configuration element attributes - * are the same as the attribute names of the corresponding XML element. - * For example, the configuration markup
+ * The names of configuration element attributes are the same as the attribute + * names of the corresponding XML element. For example, the configuration markup + * + * ** <bg pattern="stripes"/> **
- * corresponds to a configuration element named "bg"
- * with an attribute named "pattern"
- * with attribute value "stripes"
.
+ * corresponds to a configuration element named "bg"
with an
+ * attribute named "pattern"
with attribute value
+ * "stripes"
.
*
- * Note that any translation specified in the plug-in manifest - * file for this attribute is not automatically applied. + * Note that any translation specified in the plug-in manifest file for this + * attribute is not automatically applied. *
* * @param name the name of the attribute * @return attribute value, ornull
if none
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
- * @deprecated The method is equivalent to the {@link #getAttribute(String)}. Contrary to its description,
- * this method returns a translated value. Use the {@link #getAttribute(String)} method instead.
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
+ * @deprecated The method is equivalent to the {@link #getAttribute(String)}.
+ * Contrary to its description, this method returns a translated
+ * value. Use the {@link #getAttribute(String)} method instead.
*/
@Deprecated
public String getAttributeAsIs(String name) throws InvalidRegistryObjectException;
/**
- * Returns the names of the attributes of this configuration element.
- * Returns an empty array if this configuration element has no attributes.
+ * Returns the names of the attributes of this configuration element. Returns an
+ * empty array if this configuration element has no attributes.
* - * The names of configuration element attributes - * are the same as the attribute names of the corresponding XML element. - * For example, the configuration markup
+ * The names of configuration element attributes are the same as the attribute + * names of the corresponding XML element. For example, the configuration markup + * + * ** <bg color="blue" pattern="stripes"/> **
- * corresponds to a configuration element named "bg"
- * with attributes named "color"
- * and "pattern"
.
+ * corresponds to a configuration element named "bg"
with
+ * attributes named "color"
and "pattern"
.
*
- * Each child corresponds to a nested - * XML element in the configuration markup. - * For example, the configuration markup
+ * Each child corresponds to a nested XML element in the configuration markup. + * For example, the configuration markup + * + * ** <view> * <verticalHint>top</verticalHint> @@ -194,24 +213,26 @@ public interface IConfigurationElement { * </view> **
- * corresponds to a configuration element, named "view"
,
- * with two children.
+ * corresponds to a configuration element, named "view"
, with two
+ * children.
*
* <wizard name="Create Project"/> *+ * * corresponds to a configuration element named
"wizard"
.
*
* @return the name of this configuration element
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
*/
public String getName() throws InvalidRegistryObjectException;
/**
- * Returns the element which contains this element. If this element
- * is an immediate child of an extension, the
- * returned value can be downcast to IExtension
.
- * Otherwise the returned value can be downcast to
+ * Returns the element which contains this element. If this element is an
+ * immediate child of an extension, the returned value can be downcast to
+ * IExtension
. Otherwise the returned value can be downcast to
* IConfigurationElement
.
*
- * @return the parent of this configuration element
- * or null
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
+ * @return the parent of this configuration element or null
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
* @since 3.0
*/
public Object getParent() throws InvalidRegistryObjectException;
/**
- * Returns the text value of this configuration element.
- * For example, the configuration markup
+ * Returns the text value of this configuration element. For example, the
+ * configuration markup
+ *
* * <script lang="javascript">.\scripts\cp.js</script> *- * corresponds to a configuration element
"script"
- * with value ".\scripts\cp.js"
.
- * Values may span multiple lines (i.e., contain carriage returns - * and/or line feeds). - *
Note that any translation specified in the plug-in manifest
- * file is automatically applied.
+ *
+ * corresponds to a configuration element "script"
with value
+ * ".\scripts\cp.js"
.
+ *
+ * Values may span multiple lines (i.e., contain carriage returns and/or line + * feeds). + *
+ * Note that any translation specified in the plug-in manifest file is + * automatically applied. *
* * @return the text value of this configuration element ornull
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
*/
public String getValue() throws InvalidRegistryObjectException;
/**
- * When multi-language support is enabled, this method returns the text value of this
- * configuration element in the specified locale, or null
if none.
+ * When multi-language support is enabled, this method returns the text value of
+ * this configuration element in the specified locale, or null
if
+ * none.
+ * + * The locale matching tries to find the best match between available + * translations and the requested locale, falling back to a more generic locale + * ("en") when the specific locale ("en_US") is not available. + *
*- * The locale matching tries to find the best match between available translations and - * the requested locale, falling back to a more generic locale ("en") when the specific - * locale ("en_US") is not available. - *
- * If multi-language support is not enabled, this method is equivalent to the method - * {@link #getValue()}. + * If multi-language support is not enabled, this method is equivalent to the + * method {@link #getValue()}. *
+ * * @param locale the requested locale * @return the text value of this configuration element in the specified locale, - * ornull
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
+ * or null
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
* @see #getValue(String)
* @see IExtensionRegistry#isMultiLanguage()
* @since org.eclipse.equinox.registry 3.5
@@ -294,74 +326,99 @@ public interface IConfigurationElement {
public String getValue(String locale) throws InvalidRegistryObjectException;
/**
- * Returns the untranslated text value of this configuration element.
- * For example, the configuration markup
+ * Returns the untranslated text value of this configuration element. For
+ * example, the configuration markup
+ *
* * <script lang="javascript">.\scripts\cp.js</script> *- * corresponds to a configuration element
"script"
- * with value ".\scripts\cp.js"
.
- * Values may span multiple lines (i.e., contain carriage returns
- * and/or line feeds).
+ *
+ * corresponds to a configuration element "script"
with value
+ * ".\scripts\cp.js"
.
+ *
+ * Values may span multiple lines (i.e., contain carriage returns and/or line + * feeds). *
- * Note that translation specified in the plug-in manifest - * file is not automatically applied. - * For example, the configuration markup
+ * Note that translation specified in the plug-in manifest file is not + * automatically applied. For example, the configuration markup + * + * ** <tooltip>#hattip</tooltip> **
- * corresponds to a configuration element, named "tooltip"
,
- * with value "#hattip"
.
+ * corresponds to a configuration element, named "tooltip"
, with
+ * value "#hattip"
.
*
null
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
- * @deprecated The method is equivalent to the {@link #getValue()}. Contrary to its description,
- * this method returns a translated value. Use the {@link #getValue()} method instead.
+ * @return the untranslated text value of this configuration element or
+ * null
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
+ * @deprecated The method is equivalent to the {@link #getValue()}. Contrary to
+ * its description, this method returns a translated value. Use the
+ * {@link #getValue()} method instead.
*/
@Deprecated
public String getValueAsIs() throws InvalidRegistryObjectException;
/**
* Returns the namespace for this configuration element. This value can be used
- * in various global facilities to discover this configuration element's contributor.
+ * in various global facilities to discover this configuration element's
+ * contributor.
*
* @return the namespace for this configuration element
- * @throws InvalidRegistryObjectException if this configuration element is no longer valid
+ * @throws InvalidRegistryObjectException if this configuration element is no
+ * longer valid
* @see IExtensionRegistry
* @since 3.1
- * @deprecated As namespace is no longer restricted to the contributor name,
- * use {@link #getNamespaceIdentifier()} to obtain namespace name or {@link #getContributor()}
- * to get the name of the contributor of this registry element.
- *
- * In the past namespace was dictated by the name of the bundle. If bundle org.abc
- * contributed registry element with Id of MyId
, the namespace of
- * the element was always set to org.abc
, producing the qualified name of
- * org.abc.MyId
.
- *
- * The namespace used to be the same as the bundle name. As a result, the {@link #getNamespace()} - * method was used both to obtain the name of the bundle and to obtain the namespace of a registry - * element. - *
- * Since 3.2, the extension registry allows elements to specify qualified name. The extension point
- * of the plug-in org.abc
could specify org.zzz.MyExtPoint
as
- * an Id. In this case, namespace name is org.zzz
, but the contributor
- * name is org.abc
.
- *
- * (The use of a simple Id is still a preferred way. Whenever possible, specify only the simple - * Id and let runtime take care of the rest.) - *
- * If your code used the {@link #getNamespace()} to obtain the name of the contributing bundle, - * use {@link #getContributor()}. The typical usage pattern here is to find a bundle name to obtain - * some information from the corresponding OSGi bundle. For example, deducing the file location - * specified as a relative path to the bundle install location would fall into this group. - *
- * If your code used the {@link #getNamespace()} to obtain the namespace of the registry element,
- * use {@link #getNamespaceIdentifier()}. Typically, this is the case when code is trying to process
- * registry elements belonging to some logical group. For example, processing notifications for all
- * elements belonging to the org.abc
namespace would fall into this category.
- *
+ * In the past namespace was dictated by the name of the bundle. If
+ * bundle org.abc
contributed registry element with Id
+ * of MyId
, the namespace of the element was always set
+ * to org.abc
, producing the qualified name of
+ * org.abc.MyId
.
+ *
+ * The namespace used to be the same as the bundle name. As a + * result, the {@link #getNamespace()} method was used both to + * obtain the name of the bundle and to obtain the namespace of a + * registry element. + *
+ *
+ * Since 3.2, the extension registry allows elements to specify
+ * qualified name. The extension point of the plug-in
+ * org.abc
could specify
+ * org.zzz.MyExtPoint
as an Id. In this case, namespace
+ * name is org.zzz
, but the contributor name is
+ * org.abc
.
+ *
+ * (The use of a simple Id is still a preferred way. Whenever + * possible, specify only the simple Id and let runtime take care of + * the rest.) + *
+ *+ * If your code used the {@link #getNamespace()} to obtain the name + * of the contributing bundle, use {@link #getContributor()}. The + * typical usage pattern here is to find a bundle name to obtain + * some information from the corresponding OSGi bundle. For example, + * deducing the file location specified as a relative path to the + * bundle install location would fall into this group. + *
+ *
+ * If your code used the {@link #getNamespace()} to obtain the
+ * namespace of the registry element, use
+ * {@link #getNamespaceIdentifier()}. Typically, this is the case
+ * when code is trying to process registry elements belonging to
+ * some logical group. For example, processing notifications for all
+ * elements belonging to the org.abc
namespace would
+ * fall into this category.
+ *
true
if the object is valid, and false
- * if it is no longer valid
+ * @return true
if the object is valid, and false
if
+ * it is no longer valid
* @since 3.1
*/
public boolean isValid();
/**
- * Returns unique identifier of the registry object from which this element was created.
- * Two configuration element instances are considered to be equal if their handle id's are same.
- * @return The handle id of the registry object from which this configuration element was created.
+ * Returns unique identifier of the registry object from which this element was
+ * created. Two configuration element instances are considered to be equal if
+ * their handle id's are same.
+ *
+ * @return The handle id of the registry object from which this configuration
+ * element was created.
* @see #equals(Object)
* @since 3.8
*/
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IContributor.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IContributor.java
index 38ff139e226..8e2d7179f9b 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IContributor.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IContributor.java
@@ -14,18 +14,23 @@
package org.eclipse.core.runtime;
/**
- * This interface describes a registry contributor - an entity that supplies information
- * to the extension registry.
+ * This interface describes a registry contributor - an entity that supplies
+ * information to the extension registry.
+ * + * Registry contributor objects can be obtained by calling + * {@link IExtensionPoint#getContributor()}, + * {@link IExtension#getContributor()}, and + * {@link IConfigurationElement#getContributor()}. Alternatively, a contributor + * factory appropriate for the registry in use can be called to directly obtain + * an IContributor object. + *
*- * Registry contributor objects can be obtained by calling {@link IExtensionPoint#getContributor()}, - * {@link IExtension#getContributor()}, and {@link IConfigurationElement#getContributor()}. - * Alternatively, a contributor factory appropriate for the registry in use can be called to directly - * obtain an IContributor object. - *
* This interface can be used without OSGi running. - *
+ *
+ ** This interface is not intended to be implemented or extended by clients. *
+ * * @see org.eclipse.core.runtime.ContributorFactoryOSGi * @see org.eclipse.core.runtime.ContributorFactorySimple * diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtension.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtension.java index 7595c3eb618..ddfa2dc49a9 100644 --- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtension.java +++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtension.java @@ -14,19 +14,21 @@ package org.eclipse.core.runtime; /** - * Interface for executable extension classes that require access to - * their configuration element, or implement an extension adapter. + * Interface for executable extension classes that require access to their + * configuration element, or implement an extension adapter. ** Extension adapters are typically required in cases where the extension - * implementation does not follow the interface rules specified - * by the provider of the extension point. In these - * cases, the role of the adapter is to map between the extension point - * interface, and the actual extension implementation. In general, adapters - * are used when attempting to plug-in existing Java implementations, or - * non-Java implementations (e.g., external executables). - *
+ * implementation does not follow the interface rules specified by the provider + * of the extension point. In these cases, the role of the adapter is to map + * between the extension point interface, and the actual extension + * implementation. In general, adapters are used when attempting to plug-in + * existing Java implementations, or non-Java implementations (e.g., external + * executables). + *
+ ** This interface can be used without OSGi running. - *
+ *
+ ** Clients may implement this interface. *
* @@ -35,49 +37,50 @@ public interface IExecutableExtension { /** * This method is called by the implementation of the method - *IConfigurationElement.createExecutableExtension
- * on a newly constructed extension, passing it its relevant configuration
- * information. Most executable extensions only make use of the first
- * two call arguments.
+ * IConfigurationElement.createExecutableExtension
on a newly
+ * constructed extension, passing it its relevant configuration information.
+ * Most executable extensions only make use of the first two call arguments.
* - * Regular executable extensions specify their Java implementation - * class name as an attribute of the configuration element for the - * extension. For example
+ * Regular executable extensions specify their Java implementation class name as + * an attribute of the configuration element for the extension. For example + * + * ** <action run="com.example.BaseAction"/> **
- * In the above example, this method would be called with a reference
- * to the <action>
element (first argument), and
- * "run"
as the name of the attribute that defined
- * this executable extension (second argument).
+ * In the above example, this method would be called with a reference to the
+ * <action>
element (first argument), and "run"
+ * as the name of the attribute that defined this executable extension (second
+ * argument).
*
- * The last parameter is for the specific use of extension adapters - * and is typically not used by regular executable extensions. + * The last parameter is for the specific use of extension adapters and is + * typically not used by regular executable extensions. *
*- * There are two supported ways of associating additional - * adapter-specific data with the configuration in a way that - * is transparent to the extension point implementor: + * There are two supported ways of associating additional adapter-specific data + * with the configuration in a way that is transparent to the extension point + * implementor: *
*
- * (1) by specifying adapter data as part of the implementation
- * class attribute value. The Java class name can be followed
- * by a ":" separator, followed by any adapter data in string
- * form. For example, if the extension point specifies an attribute
- * "run"
to contain the name of the extension implementation,
- * an adapter can be configured as
+ * (1) by specifying adapter data as part of the implementation class attribute
+ * value. The Java class name can be followed by a ":" separator, followed by
+ * any adapter data in string form. For example, if the extension point
+ * specifies an attribute "run"
to contain the name of the
+ * extension implementation, an adapter can be configured as
*
* <action run="com.example.ExternalAdapter:./cmds/util.exe -opt 3"/> **
- * (2) by converting the attribute used to specify the executable - * extension to a child element of the original configuration element, - * and specifying the adapter data in the form of xml markup. - * Using this form, the example above would become + * (2) by converting the attribute used to specify the executable extension to a + * child element of the original configuration element, and specifying the + * adapter data in the form of xml markup. Using this form, the example above + * would become *
+ * ** <action> * <run class="com.xyz.ExternalAdapter"> @@ -87,37 +90,40 @@ public interface IExecutableExtension { * </action> **
- * Form (2) will typically only be - * used for extension points that anticipate the majority of - * extensions configured into it will in fact be in the form - * of adapters. + * Form (2) will typically only be used for extension points that anticipate the + * majority of extensions configured into it will in fact be in the form of + * adapters. *
** In either case, the specified adapter class is instantiated using its - * 0-argument public constructor. The adapter data is passed as the - * last argument of this method. The data argument is defined as Object. - * It can have the following values: + * 0-argument public constructor. The adapter data is passed as the last + * argument of this method. The data argument is defined as Object. It can have + * the following values: *
*null
, if no adapter data was suppliedString
Hashtable
containing the actual
- * parameter names and values (both String
s)String
Hashtable
containing the actual parameter names and values (both
+ * String
s)createExecutableExtension(String)
call. This
- * argument can be used in the cases where a single configuration element
- * is used to define multiple executable extensions.
- * @param data adapter data in the form of a String
,
- * a Hashtable
, or null
.
- * @exception CoreException if error(s) detected during initialization processing
+ * used on the
+ * createExecutableExtension(String)
call. This
+ * argument can be used in the cases where a single
+ * configuration element is used to define multiple
+ * executable extensions.
+ * @param data adapter data in the form of a String
, a
+ * Hashtable
, or null
.
+ * @exception CoreException if error(s) detected during initialization
+ * processing
* @see IConfigurationElement#createExecutableExtension(String)
*/
- public void setInitializationData(IConfigurationElement config, String propertyName, Object data) throws CoreException;
+ public void setInitializationData(IConfigurationElement config, String propertyName, Object data)
+ throws CoreException;
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtensionFactory.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtensionFactory.java
index 00a6b9d8c9c..b4606cce206 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtensionFactory.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExecutableExtensionFactory.java
@@ -14,10 +14,14 @@
package org.eclipse.core.runtime;
/**
- * This interface allows extension providers to control how the instances provided to extension-points are being created
- * by referring to the factory instead of referring to a class. For example, the following extension to the preference page
- * extension-point uses a factory called PreferencePageFactory
.
- *
+ * This interface allows extension providers to control how the instances
+ * provided to extension-points are being created by referring to the factory
+ * instead of referring to a class. For example, the following extension to the
+ * preference page extension-point uses a factory called
+ * PreferencePageFactory
.
+ *
+ *
+ *
* <extension point="org.eclipse.ui.preferencePages">
* <page name="..." class="org.eclipse.update.ui.PreferencePageFactory:org.eclipse.update.ui.preferences.MainPreferencePage">
* </page>
@@ -27,23 +31,31 @@
*
*
*
- * Effectively, factories give full control over the create executable extension process.
- *
- * The factories are responsible for handling the case where the concrete instance implement {@link IExecutableExtension}.
- *
- * Given that factories are instantiated as executable extensions, they must provide a 0-argument public constructor.
- * Like any other executable extension, they can configured by implementing {@link org.eclipse.core.runtime.IExecutableExtension} interface.
- *
+ * Effectively, factories give full control over the create executable extension
+ * process.
+ *
+ *
+ * The factories are responsible for handling the case where the concrete
+ * instance implement {@link IExecutableExtension}.
+ *
+ *
+ * Given that factories are instantiated as executable extensions, they must
+ * provide a 0-argument public constructor. Like any other executable extension,
+ * they can configured by implementing
+ * {@link org.eclipse.core.runtime.IExecutableExtension} interface.
+ *
+ *
* This interface can be used without OSGi running.
*
+ *
* @see org.eclipse.core.runtime.IConfigurationElement
*/
public interface IExecutableExtensionFactory {
/**
* Creates and returns a new instance.
*
- * @exception CoreException if an instance of the executable extension
- * could not be created for any reason
+ * @exception CoreException if an instance of the executable extension could not
+ * be created for any reason
*/
Object create() throws CoreException;
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionDelta.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionDelta.java
index 0c822e34f43..d4a35047ac6 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionDelta.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionDelta.java
@@ -17,9 +17,11 @@
* An extension delta represents changes to the extension registry.
*
* This interface can be used without OSGi running.
- *
+ *
+ *
* This interface is not intended to be implemented by clients.
*
+ *
* @since 3.0
* @noimplement This interface is not intended to be implemented by clients.
*/
@@ -27,12 +29,14 @@ public interface IExtensionDelta {
/**
* Delta kind constant indicating that an extension has been added to an
* extension point.
+ *
* @see IExtensionDelta#getKind()
*/
public int ADDED = 1;
/**
* Delta kind constant indicating that an extension has been removed from an
* extension point.
+ *
* @see IExtensionDelta#getKind()
*/
public int REMOVED = 2;
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionPoint.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionPoint.java
index 65cb83e117b..606dd428a33 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionPoint.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionPoint.java
@@ -14,90 +14,112 @@
package org.eclipse.core.runtime;
/**
- * An extension point declared in a plug-in.
- * Except for the list of extensions plugged in to it, the information
- * available for an extension point is obtained from the declaring plug-in's
- * manifest (plugin.xml
) file.
+ * An extension point declared in a plug-in. Except for the list of extensions
+ * plugged in to it, the information available for an extension point is
+ * obtained from the declaring plug-in's manifest (plugin.xml
)
+ * file.
+ *
+ * These registry objects are intended for relatively short-term use. Clients
+ * that deal with these objects must be aware that they may become invalid if
+ * the declaring plug-in is updated or uninstalled. If this happens, all methods
+ * except {@link #isValid()} will throw {@link InvalidRegistryObjectException}.
+ * For extension point objects, the most common case is code in a plug-in
+ * dealing with one of the extension points it declares. These extension point
+ * objects are guaranteed to be valid while the plug-in is active. Code in a
+ * plug-in that has declared that it is not dynamic aware (or not declared
+ * anything) can also safely ignore this issue, since the registry would not be
+ * modified while it is active. However, code in a plug-in that declares that it
+ * is dynamic aware must be careful if it access the extension point object of a
+ * different plug-in, because it's at risk if that other plug-in is removed.
+ * Similarly, tools that analyze or display the extension registry are
+ * vulnerable. Client code can pre-test for invalid objects by calling
+ * {@link #isValid()}, which never throws this exception. However, pre-tests are
+ * usually not sufficient because of the possibility of the extension point
+ * object becoming invalid as a result of a concurrent activity. At-risk clients
+ * must treat InvalidRegistryObjectException
as if it were a
+ * checked exception. Also, such clients should probably register a listener
+ * with the extension registry so that they receive notification of any changes
+ * to the registry.
+ *
*
- * These registry objects are intended for relatively short-term use. Clients that
- * deal with these objects must be aware that they may become invalid if the
- * declaring plug-in is updated or uninstalled. If this happens, all methods except
- * {@link #isValid()} will throw {@link InvalidRegistryObjectException}.
- * For extension point objects, the most common case is code in a plug-in dealing
- * with one of the extension points it declares. These extension point objects are
- * guaranteed to be valid while the plug-in is active. Code in a plug-in that has
- * declared that it is not dynamic aware (or not declared anything) can also safely
- * ignore this issue, since the registry would not be modified while it is
- * active. However, code in a plug-in that declares that it is dynamic aware
- * must be careful if it access the extension point object of a different plug-in,
- * because it's at risk if that other plug-in is removed. Similarly,
- * tools that analyze or display the extension registry are vulnerable.
- * Client code can pre-test for invalid objects by calling {@link #isValid()},
- * which never throws this exception. However, pre-tests are usually not sufficient
- * because of the possibility of the extension point object becoming invalid as a
- * result of a concurrent activity. At-risk clients must treat
- * InvalidRegistryObjectException
as if it were a checked exception.
- * Also, such clients should probably register a listener with the extension registry
- * so that they receive notification of any changes to the registry.
- *
* This interface can be used without OSGi running.
- *
+ *
+ *
* This interface is not intended to be implemented by clients.
*
+ *
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IExtensionPoint {
/**
- * Returns all configuration elements from all extensions configured
- * into this extension point. Returns an empty array if this extension
- * point has no extensions configured, or none of the extensions
- * contain configuration elements.
+ * Returns all configuration elements from all extensions configured into this
+ * extension point. Returns an empty array if this extension point has no
+ * extensions configured, or none of the extensions contain configuration
+ * elements.
*
- * @return the configuration elements for all extension configured
- * into this extension point
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @return the configuration elements for all extension configured into this
+ * extension point
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
*/
public IConfigurationElement[] getConfigurationElements() throws InvalidRegistryObjectException;
/**
- * Returns the namespace for this extension point. This value can be used
- * in various global facilities to discover this extension point's provider.
+ * Returns the namespace for this extension point. This value can be used in
+ * various global facilities to discover this extension point's provider.
*
* @return the namespace for this extension point
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
* @see IExtensionRegistry
* @since 3.0
- * @deprecated As namespace is no longer restricted to the contributor name,
- * use {@link #getNamespaceIdentifier()} to obtain namespace name or {@link #getContributor()}
- * to get the name of the contributor of this registry element.
- *
- * In the past namespace was dictated by the name of the bundle. If bundle org.abc
- * contributed registry element with Id of MyId
, the namespace of
- * the element was always set to org.abc
, producing the qualified name of
- * org.abc.MyId
.
- *
- * The namespace used to be the same as the bundle name. As a result, the {@link #getNamespace()}
- * method was used both to obtain the name of the bundle and to obtain the namespace of a registry
- * element.
- *
- * Since 3.2, the extension registry allows elements to specify qualified name. The extension point
- * of the plug-in org.abc
could specify org.zzz.MyExtPoint
as
- * an Id. In this case, namespace name is org.zzz
, but the contributor
- * name is org.abc
.
- *
- * (The use of a simple Id is still a preferred way. Whenever possible, specify only the simple
- * Id and let runtime take care of the rest.)
- *
- * If your code used the {@link #getNamespace()} to obtain the name of the contributing bundle,
- * use {@link #getContributor()}. The typical usage pattern here is to find a bundle name to obtain
- * some information from the corresponding OSGi bundle. For example, deducing the file location
- * specified as a relative path to the bundle install location would fall into this group.
- *
- * If your code used the {@link #getNamespace()} to obtain the namespace of the registry element,
- * use {@link #getNamespaceIdentifier()}. Typically, this is the case when code is trying to process
- * registry elements belonging to some logical group. For example, processing notifications for all
- * elements belonging to the org.abc
namespace would fall into this category.
- *
+ * @deprecated As namespace is no longer restricted to the contributor name, use
+ * {@link #getNamespaceIdentifier()} to obtain namespace name or
+ * {@link #getContributor()} to get the name of the contributor of
+ * this registry element.
+ *
+ * In the past namespace was dictated by the name of the bundle. If
+ * bundle org.abc
contributed registry element with Id
+ * of MyId
, the namespace of the element was always set
+ * to org.abc
, producing the qualified name of
+ * org.abc.MyId
.
+ *
+ *
+ * The namespace used to be the same as the bundle name. As a
+ * result, the {@link #getNamespace()} method was used both to
+ * obtain the name of the bundle and to obtain the namespace of a
+ * registry element.
+ *
+ *
+ * Since 3.2, the extension registry allows elements to specify
+ * qualified name. The extension point of the plug-in
+ * org.abc
could specify
+ * org.zzz.MyExtPoint
as an Id. In this case, namespace
+ * name is org.zzz
, but the contributor name is
+ * org.abc
.
+ *
+ *
+ * (The use of a simple Id is still a preferred way. Whenever
+ * possible, specify only the simple Id and let runtime take care of
+ * the rest.)
+ *
+ *
+ * If your code used the {@link #getNamespace()} to obtain the name
+ * of the contributing bundle, use {@link #getContributor()}. The
+ * typical usage pattern here is to find a bundle name to obtain
+ * some information from the corresponding OSGi bundle. For example,
+ * deducing the file location specified as a relative path to the
+ * bundle install location would fall into this group.
+ *
+ *
+ * If your code used the {@link #getNamespace()} to obtain the
+ * namespace of the registry element, use
+ * {@link #getNamespaceIdentifier()}. Typically, this is the case
+ * when code is trying to process registry elements belonging to
+ * some logical group. For example, processing notifications for all
+ * elements belonging to the org.abc
namespace would
+ * fall into this category.
+ *
*/
public String getNamespace() throws InvalidRegistryObjectException;
@@ -105,7 +127,8 @@ public interface IExtensionPoint {
* Returns the namespace name for this extension point.
*
* @return the namespace name for this extension point
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
* @since org.eclipse.equinox.registry 3.2
*/
public String getNamespaceIdentifier() throws InvalidRegistryObjectException;
@@ -114,106 +137,117 @@ public interface IExtensionPoint {
* Returns the contributor of this extension point.
*
* @return the contributor for this extension point
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
* @since org.eclipse.equinox.registry 3.2
*/
public IContributor getContributor() throws InvalidRegistryObjectException;
/**
- * Returns the extension with the given unique identifier configured into
- * this extension point, or null
if there is no such extension.
- * Since an extension might not have an identifier, some extensions
- * can only be found via the getExtensions
method.
+ * Returns the extension with the given unique identifier configured into this
+ * extension point, or null
if there is no such extension. Since an
+ * extension might not have an identifier, some extensions can only be found via
+ * the getExtensions
method.
*
- * @param extensionId the unique identifier of an extension
- * (e.g. "com.example.acme.main"
).
+ * @param extensionId the unique identifier of an extension (e.g.
+ * "com.example.acme.main"
).
* @return an extension, or null
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
*/
public IExtension getExtension(String extensionId) throws InvalidRegistryObjectException;
/**
- * Returns all extensions configured into this extension point.
- * Returns an empty array if this extension point has no extensions.
+ * Returns all extensions configured into this extension point. Returns an empty
+ * array if this extension point has no extensions.
*
* @return the extensions configured into this extension point
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
*/
public IExtension[] getExtensions() throws InvalidRegistryObjectException;
/**
- * Returns a displayable label for this extension point.
- * Returns the empty string if no label for this extension point
- * is specified in the plug-in manifest file.
- * Note that any translation specified in the plug-in manifest
- * file is automatically applied.
+ * Returns a displayable label for this extension point. Returns the empty
+ * string if no label for this extension point is specified in the plug-in
+ * manifest file.
+ *
+ * Note that any translation specified in the plug-in manifest file is
+ * automatically applied.
*
*
- * @return a displayable string label for this extension point,
- * possibly the empty string
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @return a displayable string label for this extension point, possibly the
+ * empty string
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
*/
public String getLabel() throws InvalidRegistryObjectException;
/**
- * When multi-language support is enabled, this method returns a displayable label
- * for this extension point in the specified locale.
- * Returns the empty string if no label for this extension point
- * is specified in the plug-in manifest file.
+ * When multi-language support is enabled, this method returns a displayable
+ * label for this extension point in the specified locale. Returns the empty
+ * string if no label for this extension point is specified in the plug-in
+ * manifest file.
+ *
+ * The locale matching tries to find the best match between available
+ * translations and the requested locale, falling back to a more generic locale
+ * ("en") when the specific locale ("en_US") is not available.
+ *
*
- * The locale matching tries to find the best match between available translations and
- * the requested locale, falling back to a more generic locale ("en") when the specific
- * locale ("en_US") is not available.
- *
- * If multi-language support is not enabled, this method is equivalent to the method
- * {@link #getLabel()}.
+ * If multi-language support is not enabled, this method is equivalent to the
+ * method {@link #getLabel()}.
*
+ *
* @param locale the requested locale
- * @return a displayable string label for this extension point,
- * possibly the empty string
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @return a displayable string label for this extension point, possibly the
+ * empty string
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
* @see IExtensionRegistry#isMultiLanguage()
* @since 3.5
*/
public String getLabel(String locale) throws InvalidRegistryObjectException;
/**
- * Returns reference to the extension point schema. The schema
- * reference is returned as a URL path relative to the plug-in
- * installation URL.
- * Returns the empty string if no schema for this extension point
- * is specified in the plug-in manifest file.
+ * Returns reference to the extension point schema. The schema reference is
+ * returned as a URL path relative to the plug-in installation URL. Returns the
+ * empty string if no schema for this extension point is specified in the
+ * plug-in manifest file.
*
* @return a relative URL path, or an empty string
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
*/
public String getSchemaReference() throws InvalidRegistryObjectException;
/**
- * Returns the simple identifier of this extension point.
- * This identifier is a non-empty string containing no
- * period characters ('.'
) and is guaranteed
- * to be unique within the namespace.
+ * Returns the simple identifier of this extension point. This identifier is a
+ * non-empty string containing no period characters ('.'
) and is
+ * guaranteed to be unique within the namespace.
*
- * @return the simple identifier of the extension point (e.g. "builders"
)
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @return the simple identifier of the extension point (e.g.
+ * "builders"
)
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
*/
public String getSimpleIdentifier() throws InvalidRegistryObjectException;
/**
- * Returns the unique identifier of this extension point.
- * This identifier is unique within the plug-in registry, and
- * is composed of the namespace for this extension point
- * and this extension point's simple identifier.
+ * Returns the unique identifier of this extension point. This identifier is
+ * unique within the plug-in registry, and is composed of the namespace for this
+ * extension point and this extension point's simple identifier.
*
*
- * @return the unique identifier of the extension point
- * (e.g. "org.eclipse.core.resources.builders"
)
- * @throws InvalidRegistryObjectException if this extension point is no longer valid
+ * @return the unique identifier of the extension point (e.g.
+ * "org.eclipse.core.resources.builders"
)
+ * @throws InvalidRegistryObjectException if this extension point is no longer
+ * valid
*/
public String getUniqueIdentifier() throws InvalidRegistryObjectException;
- /* (non-javadoc)
+ /*
+ * (non-javadoc)
+ *
* @see Object#equals(java.lang.Object)
*/
@Override
@@ -222,8 +256,8 @@ public interface IExtensionPoint {
/**
* Returns whether this extension point object is valid.
*
- * @return true
if the object is valid, and false
- * if it is no longer valid
+ * @return true
if the object is valid, and false
if
+ * it is no longer valid
* @since 3.1
*/
public boolean isValid();
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionRegistry.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionRegistry.java
index 5ec344b135a..31130857782 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionRegistry.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IExtensionRegistry.java
@@ -17,63 +17,70 @@
import java.util.ResourceBundle;
/**
- * The extension registry holds the master list of all
- * discovered namespaces, extension points and extensions.
- *
- * The extension registry can be queried, by name, for
+ * The extension registry holds the master list of all discovered namespaces,
* extension points and extensions.
+ *
+ * The extension registry can be queried, by name, for extension points and
+ * extensions.
*
*
* The various objects that describe the contents of the extension registry
- * ({@link IExtensionPoint}, {@link IExtension}, and {@link IConfigurationElement})
- * are intended for relatively short-term use. Clients that deal with these objects
- * must be aware that they may become invalid if the declaring plug-in is updated
- * or uninstalled. If this happens, all methods on these object except
- * isValid()
will throw {@link org.eclipse.core.runtime.InvalidRegistryObjectException}.
- * Code in a plug-in that has declared that it is not dynamic aware (or not declared
+ * ({@link IExtensionPoint}, {@link IExtension}, and
+ * {@link IConfigurationElement}) are intended for relatively short-term use.
+ * Clients that deal with these objects must be aware that they may become
+ * invalid if the declaring plug-in is updated or uninstalled. If this happens,
+ * all methods on these object except isValid()
will throw
+ * {@link org.eclipse.core.runtime.InvalidRegistryObjectException}. Code in a
+ * plug-in that has declared that it is not dynamic aware (or not declared
* anything) can safely ignore this issue, since the registry would not be
* modified while it is active. However, code in a plug-in that declares that it
* is dynamic aware must be careful if it accesses extension registry objects,
- * because it's at risk if plug-in are removed. Similarly, tools that analyze
- * or display the extension registry are vulnerable. Client code can pre-test for
- * invalid objects by calling isValid()
, which never throws this exception.
- * However, pre-tests are usually not sufficient because of the possibility of the
- * extension registry object becoming invalid as a result of a concurrent activity.
- * At-risk clients must treat InvalidRegistryObjectException
as if it
- * were a checked exception. Also, such clients should probably register a listener
- * with the extension registry so that they receive notification of any changes to
- * the registry.
+ * because it's at risk if plug-in are removed. Similarly, tools that analyze or
+ * display the extension registry are vulnerable. Client code can pre-test for
+ * invalid objects by calling isValid()
, which never throws this
+ * exception. However, pre-tests are usually not sufficient because of the
+ * possibility of the extension registry object becoming invalid as a result of
+ * a concurrent activity. At-risk clients must treat
+ * InvalidRegistryObjectException
as if it were a checked
+ * exception. Also, such clients should probably register a listener with the
+ * extension registry so that they receive notification of any changes to the
+ * registry.
*
*
* Extensions and extension points are declared by generic entities called
* namespaces. The only fact known about namespaces is that they
- * have unique string-based identifiers. One example of a namespace
- * is a plug-in, for which the namespace id is the plug-in id.
- *
+ * have unique string-based identifiers. One example of a namespace is a
+ * plug-in, for which the namespace id is the plug-in id.
+ *
+ *
* This interface can be used without OSGi running.
- *
+ *
+ *
* This interface is not intended to be implemented by clients.
*
+ *
* @since 3.0
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IExtensionRegistry {
/**
- * Note: for new implementations consider using {@link #addListener(IRegistryEventListener, String)}.
+ * Note: for new implementations consider using
+ * {@link #addListener(IRegistryEventListener, String)}.
*
- * Adds the given listener for registry change events related to extension points
- * in the given namespace.
- * Has no effect if an identical listener is already registered. After
- * completion of this method, the given listener will be registered for events
- * related to extension points in the specified namespace. If no namespace
- * is specified, the listener will receive notifications for changes to
- * extension points in any namespace.
- *
- * Once registered, a listener starts receiving notification of changes to
- * the registry. Registry change notifications are sent asynchronously.
- * The listener continues to receive notifications until it is removed.
+ * Adds the given listener for registry change events related to extension
+ * points in the given namespace. Has no effect if an identical listener is
+ * already registered. After completion of this method, the given listener will
+ * be registered for events related to extension points in the specified
+ * namespace. If no namespace is specified, the listener will receive
+ * notifications for changes to extension points in any namespace.
*
- * @param listener the listener
+ *
+ * Once registered, a listener starts receiving notification of changes to the
+ * registry. Registry change notifications are sent asynchronously. The listener
+ * continues to receive notifications until it is removed.
+ *
+ *
+ * @param listener the listener
* @param namespace the namespace in which to listen for changes
* @see IRegistryChangeListener
* @see IRegistryChangeEvent
@@ -82,16 +89,19 @@ public interface IExtensionRegistry {
public void addRegistryChangeListener(IRegistryChangeListener listener, String namespace);
/**
- * Note: for new implementations consider using {@link #addListener(IRegistryEventListener)}.
+ * Note: for new implementations consider using
+ * {@link #addListener(IRegistryEventListener)}.
*
- * Adds the given listener for registry change events.
- * Has no effect if an identical listener is already registered.
+ * Adds the given listener for registry change events. Has no effect if an
+ * identical listener is already registered.
*
- *
+ *
+ *
* This method is equivalent to:
*
+ *
*
- * addRegistryChangeListener(listener,null);
+ * addRegistryChangeListener(listener, null);
*
*
* @param listener the listener
@@ -103,176 +113,178 @@ public interface IExtensionRegistry {
public void addRegistryChangeListener(IRegistryChangeListener listener);
/**
- * Returns all configuration elements from all extensions configured
- * into the identified extension point. Returns an empty array if the extension
- * point does not exist, has no extensions configured, or none of the extensions
+ * Returns all configuration elements from all extensions configured into the
+ * identified extension point. Returns an empty array if the extension point
+ * does not exist, has no extensions configured, or none of the extensions
* contain configuration elements.
*
- * @param extensionPointId the unique identifier of the extension point
- * (e.g. "org.eclipse.core.resources.builders"
)
+ * @param extensionPointId the unique identifier of the extension point (e.g.
+ * "org.eclipse.core.resources.builders"
)
* @return the configuration elements
*/
public IConfigurationElement[] getConfigurationElementsFor(String extensionPointId);
/**
- * Returns all configuration elements from all extensions configured
- * into the identified extension point. Returns an empty array if the extension
- * point does not exist, has no extensions configured, or none of the extensions
+ * Returns all configuration elements from all extensions configured into the
+ * identified extension point. Returns an empty array if the extension point
+ * does not exist, has no extensions configured, or none of the extensions
* contain configuration elements.
*
- * @param namespace the namespace for the extension point
- * (e.g. "org.eclipse.core.resources"
)
- * @param extensionPointName the simple identifier of the
- * extension point (e.g. "builders"
)
+ * @param namespace the namespace for the extension point (e.g.
+ * "org.eclipse.core.resources"
)
+ * @param extensionPointName the simple identifier of the extension point (e.g.
+ * "builders"
)
* @return the configuration elements
*/
public IConfigurationElement[] getConfigurationElementsFor(String namespace, String extensionPointName);
/**
- * Returns all configuration elements from the identified extension.
- * Returns an empty array if the extension does not exist or
- * contains no configuration elements.
+ * Returns all configuration elements from the identified extension. Returns an
+ * empty array if the extension does not exist or contains no configuration
+ * elements.
*
- * @param namespace the namespace for the extension point
- * (e.g. "org.eclipse.core.resources"
)
- * @param extensionPointName the simple identifier of the
- * extension point (e.g. "builders"
)
- * @param extensionId the unique identifier of the extension
- * (e.g. "com.example.acme.coolbuilder"
)
+ * @param namespace the namespace for the extension point (e.g.
+ * "org.eclipse.core.resources"
)
+ * @param extensionPointName the simple identifier of the extension point (e.g.
+ * "builders"
)
+ * @param extensionId the unique identifier of the extension (e.g.
+ * "com.example.acme.coolbuilder"
)
* @return the configuration elements
*/
- public IConfigurationElement[] getConfigurationElementsFor(String namespace, String extensionPointName, String extensionId);
+ public IConfigurationElement[] getConfigurationElementsFor(String namespace, String extensionPointName,
+ String extensionId);
/**
- * Returns the specified extension in this extension registry,
- * or null
if there is no such extension.
+ * Returns the specified extension in this extension registry, or
+ * null
if there is no such extension.
*
- * @param extensionId the unique identifier of the extension
- * (e.g. "com.example.acme.coolbuilder"
)
+ * @param extensionId the unique identifier of the extension (e.g.
+ * "com.example.acme.coolbuilder"
)
* @return the extension, or null
*/
public IExtension getExtension(String extensionId);
/**
- * Returns the specified extension in this extension registry,
- * or null
if there is no such extension.
- * The first parameter identifies the extension point, and the second
- * parameter identifies an extension plugged in to that extension point.
+ * Returns the specified extension in this extension registry, or
+ * null
if there is no such extension. The first parameter
+ * identifies the extension point, and the second parameter identifies an
+ * extension plugged in to that extension point.
*
- * @param extensionPointId the unique identifier of the extension point
- * (e.g. "org.eclipse.core.resources.builders"
)
- * @param extensionId the unique identifier of the extension
- * (e.g. "com.example.acme.coolbuilder"
)
+ * @param extensionPointId the unique identifier of the extension point (e.g.
+ * "org.eclipse.core.resources.builders"
)
+ * @param extensionId the unique identifier of the extension (e.g.
+ * "com.example.acme.coolbuilder"
)
* @return the extension, or null
*/
public IExtension getExtension(String extensionPointId, String extensionId);
/**
- * Returns the specified extension in this extension registry,
- * or null
if there is no such extension.
- * The first two parameters identify the extension point, and the third
- * parameter identifies an extension plugged in to that extension point.
+ * Returns the specified extension in this extension registry, or
+ * null
if there is no such extension. The first two parameters
+ * identify the extension point, and the third parameter identifies an extension
+ * plugged in to that extension point.
*
- * @param namespace the namespace for the extension point
- * (e.g. "org.eclipse.core.resources"
)
- * @param extensionPointName the simple identifier of the
- * extension point (e.g. "builders"
)
- * @param extensionId the unique identifier of the extension
- * (e.g. "com.example.acme.coolbuilder"
)
+ * @param namespace the namespace for the extension point (e.g.
+ * "org.eclipse.core.resources"
)
+ * @param extensionPointName the simple identifier of the extension point (e.g.
+ * "builders"
)
+ * @param extensionId the unique identifier of the extension (e.g.
+ * "com.example.acme.coolbuilder"
)
* @return the extension, or null
*/
public IExtension getExtension(String namespace, String extensionPointName, String extensionId);
/**
- * Returns the extension point with the given extension point identifier
- * in this extension registry, or null
if there is no such
- * extension point.
+ * Returns the extension point with the given extension point identifier in this
+ * extension registry, or null
if there is no such extension point.
*
- * @param extensionPointId the unique identifier of the extension point
- * (e.g., "org.eclipse.core.resources.builders"
)
+ * @param extensionPointId the unique identifier of the extension point (e.g.,
+ * "org.eclipse.core.resources.builders"
)
* @return the extension point, or null
*/
public IExtensionPoint getExtensionPoint(String extensionPointId);
/**
- * Returns the extension point in this extension registry
- * with the given namespace and extension point simple identifier,
- * or null
if there is no such extension point.
+ * Returns the extension point in this extension registry with the given
+ * namespace and extension point simple identifier, or null
if
+ * there is no such extension point.
*
- * @param namespace the namespace for the given extension point
- * (e.g. "org.eclipse.core.resources"
)
- * @param extensionPointName the simple identifier of the
- * extension point (e.g. "builders"
)
+ * @param namespace the namespace for the given extension point (e.g.
+ * "org.eclipse.core.resources"
)
+ * @param extensionPointName the simple identifier of the extension point (e.g.
+ * "builders"
)
* @return the extension point, or null
*/
public IExtensionPoint getExtensionPoint(String namespace, String extensionPointName);
/**
- * Returns all extension points known to this extension registry.
- * Returns an empty array if there are no extension points.
+ * Returns all extension points known to this extension registry. Returns an
+ * empty array if there are no extension points.
*
* @return the extension points known to this extension registry
*/
public IExtensionPoint[] getExtensionPoints();
/**
- * Returns all extension points declared in the given namespace. Returns an empty array if
- * there are no extension points declared in the namespace.
+ * Returns all extension points declared in the given namespace. Returns an
+ * empty array if there are no extension points declared in the namespace.
*
- * @param namespace the namespace for the extension points
- * (e.g. "org.eclipse.core.resources"
)
+ * @param namespace the namespace for the extension points (e.g.
+ * "org.eclipse.core.resources"
)
* @return the extension points in this registry declared in the given namespace
*/
public IExtensionPoint[] getExtensionPoints(String namespace);
/**
- * Returns all extension points supplied by the contributor, or null
- * if there are no such extension points.
+ * Returns all extension points supplied by the contributor, or
+ * null
if there are no such extension points.
*
- * @param contributor the contributor for the extensions (for OSGi registry, bundles and
- * fragments are different contributors)
+ * @param contributor the contributor for the extensions (for OSGi registry,
+ * bundles and fragments are different contributors)
* @return the extension points, or null
* @since 3.4
*/
public IExtensionPoint[] getExtensionPoints(IContributor contributor);
/**
- * Returns all extensions declared in the given namespace. Returns an empty array if
- * no extensions are declared in the namespace.
+ * Returns all extensions declared in the given namespace. Returns an empty
+ * array if no extensions are declared in the namespace.
*
- * @param namespace the namespace for the extensions
- * (e.g. "org.eclipse.core.resources"
)
+ * @param namespace the namespace for the extensions (e.g.
+ * "org.eclipse.core.resources"
)
* @return the extensions in this registry declared in the given namespace
*/
public IExtension[] getExtensions(String namespace);
/**
- * Returns all extensions supplied by the contributor, or null
if there
- * are no such extensions.
- * @param contributor the contributor for the extensions (for OSGi registry, bundles and
- * fragments are different contributors)
+ * Returns all extensions supplied by the contributor, or null
if
+ * there are no such extensions.
+ *
+ * @param contributor the contributor for the extensions (for OSGi registry,
+ * bundles and fragments are different contributors)
* @return the extensions, or null
* @since 3.4
*/
public IExtension[] getExtensions(IContributor contributor);
/**
- * Returns all namespaces currently used by extensions and extension points in this
- * registry. Returns an empty array if there are no known extensions/extension points
- * in this registry.
+ * Returns all namespaces currently used by extensions and extension points in
+ * this registry. Returns an empty array if there are no known
+ * extensions/extension points in this registry.
*
- * The fully-qualified name of an extension point or an extension consist of
- * a namespace and a simple name (much like a qualified Java class name consist
- * of a package name and a class name). The simple names are presumed to be unique
+ * The fully-qualified name of an extension point or an extension consist of a
+ * namespace and a simple name (much like a qualified Java class name consist of
+ * a package name and a class name). The simple names are presumed to be unique
* in the namespace.
*
+ *
* @return all namespaces known to this registry
*/
public String[] getNamespaces();
/**
- * Removes the given registry change listener from this registry.
- * Has no effect if an identical listener is not registered.
+ * Removes the given registry change listener from this registry. Has no effect
+ * if an identical listener is not registered.
*
* @param listener the listener
* @see IRegistryChangeListener
@@ -282,49 +294,60 @@ public interface IExtensionRegistry {
public void removeRegistryChangeListener(IRegistryChangeListener listener);
/**
- * Adds to this extension registry an extension point(s), extension(s), or
- * a combination of those described by the XML file. The information in
- * the XML file should be supplied in the same format as the plugin.xml; in fact,
- * Plug-in Manifest editor can be used to prepare the XML file. The top token
- * of the contribution (normally, "plugin" or "fragment" in the Plug-in Manifest
+ * Adds to this extension registry an extension point(s), extension(s), or a
+ * combination of those described by the XML file. The information in the XML
+ * file should be supplied in the same format as the plugin.xml; in fact,
+ * Plug-in Manifest editor can be used to prepare the XML file. The top token of
+ * the contribution (normally, "plugin" or "fragment" in the Plug-in Manifest
* editor) is ignored by this method.
*
- * This method is an access controlled method. Proper token (master token or user token) should
- * be passed as an argument. Two registry keys are set in the registry constructor
+ * This method is an access controlled method. Proper token (master token or
+ * user token) should be passed as an argument. Two registry keys are set in the
+ * registry constructor
* {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
- * master token and a user token. Master token allows all operations; user token allows
- * non-persisted registry elements to be modified.
+ * master token and a user token. Master token allows all operations; user token
+ * allows non-persisted registry elements to be modified.
*
- * @param is stream open on the XML file. The XML file can contain an extension
- * point(s) or/and extension(s) described in the format similar to plugin.xml. The method
- * closes the stream before returning
- * @param contributor the contributor making this contribution.
- * @param persist indicates if the contribution(s) should be stored in the registry cache. If false
,
- * contribution is not persisted in the registry cache and is lost on Eclipse restart
- * @param name optional name of the contribution. Used for error reporting; might be null
- * @param translationBundle optional resource bundle used for translations; might be null
- * @param token the key used to check permissions
- * @return true
if the contribution was successfully processed and false
- * otherwise
+ *
+ * @param is stream open on the XML file. The XML file can
+ * contain an extension point(s) or/and extension(s)
+ * described in the format similar to plugin.xml. The
+ * method closes the stream before returning
+ * @param contributor the contributor making this contribution.
+ * @param persist indicates if the contribution(s) should be stored in
+ * the registry cache. If false
,
+ * contribution is not persisted in the registry cache
+ * and is lost on Eclipse restart
+ * @param name optional name of the contribution. Used for error
+ * reporting; might be null
+ * @param translationBundle optional resource bundle used for translations;
+ * might be null
+ * @param token the key used to check permissions
+ * @return true
if the contribution was successfully processed and
+ * false
otherwise
* @throws IllegalArgumentException if an incorrect token is passed
*
* @see IContributor
* @since org.eclipse.equinox.registry 3.2
*/
- public boolean addContribution(InputStream is, IContributor contributor, boolean persist, String name, ResourceBundle translationBundle, Object token) throws IllegalArgumentException;
+ public boolean addContribution(InputStream is, IContributor contributor, boolean persist, String name,
+ ResourceBundle translationBundle, Object token) throws IllegalArgumentException;
/**
* Removes the given extension from this registry.
*
- * This method is an access controlled method. Proper token (master token or user token) should
- * be passed as an argument. Two registry keys are set in the registry constructor
+ * This method is an access controlled method. Proper token (master token or
+ * user token) should be passed as an argument. Two registry keys are set in the
+ * registry constructor
* {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
- * master token and a user token. Master token allows all operations; user token only
- * allows non-persisted registry elements to be modified.
+ * master token and a user token. Master token allows all operations; user token
+ * only allows non-persisted registry elements to be modified.
*
+ *
* @param extension extension to be removed
- * @param token the key used to check permissions
- * @return true
if the extension was successfully removed, and false
otherwise
+ * @param token the key used to check permissions
+ * @return true
if the extension was successfully removed, and
+ * false
otherwise
* @throws IllegalArgumentException if an incorrect token is passed
*
* @since org.eclipse.equinox.registry 3.2
@@ -334,16 +357,18 @@ public interface IExtensionRegistry {
/**
* Removes the specified extension point from this registry.
*
- * This method is an access controlled method. Proper token (master token or user token) should
- * be passed as an argument. Two registry keys are set in the registry constructor
+ * This method is an access controlled method. Proper token (master token or
+ * user token) should be passed as an argument. Two registry keys are set in the
+ * registry constructor
* {@link RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)}:
- * master token and a user token. Master token allows all operations; user token only
- * allows non-persisted registry elements to be modified.
+ * master token and a user token. Master token allows all operations; user token
+ * only allows non-persisted registry elements to be modified.
*
+ *
* @param extensionPoint extension point to be removed
- * @param token the key used to check permissions
- * @return true
if the extension point was successfully removed, and
- * false
otherwise
+ * @param token the key used to check permissions
+ * @return true
if the extension point was successfully removed,
+ * and false
otherwise
* @throws IllegalArgumentException if incorrect token is passed
*
* @since org.eclipse.equinox.registry 3.2
@@ -351,13 +376,16 @@ public interface IExtensionRegistry {
public boolean removeExtensionPoint(IExtensionPoint extensionPoint, Object token) throws IllegalArgumentException;
/**
- * Call this method to properly stop the registry. The method stops registry event processing
- * and writes out cache information to be used in the next run. This is an access controlled
- * method; master token is required.
+ * Call this method to properly stop the registry. The method stops registry
+ * event processing and writes out cache information to be used in the next run.
+ * This is an access controlled method; master token is required.
*
- * This method is an access controlled method. Master token should be passed as an argument.
+ * This method is an access controlled method. Master token should be passed as
+ * an argument.
*
- * @see RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy, Object, Object)
+ *
+ * @see RegistryFactory#createRegistry(org.eclipse.core.runtime.spi.RegistryStrategy,
+ * Object, Object)
* @param token master token for the registry
* @throws IllegalArgumentException if incorrect token is passed
*
@@ -369,17 +397,20 @@ public interface IExtensionRegistry {
* Adds the given listener for registry change events. Listener will be notified
* on changes to all extension points and underlying extensions.
*
- * Depending on activity, listeners of this type might receive a large number
- * of modifications and negatively impact overall system performance. Whenever
+ * Depending on activity, listeners of this type might receive a large number of
+ * modifications and negatively impact overall system performance. Whenever
* possible, consider registering listener specific to an extension point rather
* than a "global" listener.
- *
- * Once registered, a listener starts receiving notification of changes to
- * the registry. Registry change notifications are sent asynchronously.
- * The listener continues to receive notifications until it is removed.
- *
+ *
+ *
+ * Once registered, a listener starts receiving notification of changes to the
+ * registry. Registry change notifications are sent asynchronously. The listener
+ * continues to receive notifications until it is removed.
+ *
+ *
* This method has no effect if the listener is already registered.
*
+ *
* @param listener the listener
* @since org.eclipse.equinox.registry 3.4
*/
@@ -389,13 +420,15 @@ public interface IExtensionRegistry {
* Adds the given listener for registry change events related to specified
* extension point.
*
- * Once registered, a listener starts receiving notification of changes to
- * the registry. Registry change notifications are sent asynchronously.
- * The listener continues to receive notifications until it is removed.
- *
+ * Once registered, a listener starts receiving notification of changes to the
+ * registry. Registry change notifications are sent asynchronously. The listener
+ * continues to receive notifications until it is removed.
+ *
+ *
* This method has no effect if the listener is already registered.
*
- * @param listener the listener
+ *
+ * @param listener the listener
* @param extensionPointId the unique identifier of extension point
* @see IExtensionPoint#getUniqueIdentifier()
* @since org.eclipse.equinox.registry 3.4
@@ -407,6 +440,7 @@ public interface IExtensionRegistry {
*
* This method has no effect if the listener is not registered.
*
+ *
* @param listener the listener
* @see #addListener(IRegistryEventListener)
* @see #addListener(IRegistryEventListener, String)
@@ -415,13 +449,15 @@ public interface IExtensionRegistry {
public void removeListener(IRegistryEventListener listener);
/**
- * Call this method to determine if this extension registry supports multiple languages.
+ * Call this method to determine if this extension registry supports multiple
+ * languages.
*
* See the runtime option "-registryMultiLanguage" for enabling multi-language
* support.
*
+ *
* @return true
if multiple languages are supported by this
- * instance of the extension registry; false
otherwise.
+ * instance of the extension registry; false
otherwise.
* @since org.eclipse.equinox.registry 3.5
*/
public boolean isMultiLanguage();
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeEvent.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeEvent.java
index f6bd811d2ca..5eb8f5230b7 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeEvent.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeEvent.java
@@ -17,9 +17,11 @@
* Registry change events describe changes to the extension registry.
*
* This interface can be used without OSGi running.
- *
+ *
+ *
* This interface is not intended to be implemented by clients.
*
+ *
* @since 3.0
* @see IExtensionRegistry
* @see IRegistryChangeListener
@@ -27,16 +29,17 @@
*/
public interface IRegistryChangeEvent {
/**
- * Returns all extension deltas for all hosts. Returns an empty array if there are
- * no deltas in this event.
+ * Returns all extension deltas for all hosts. Returns an empty array if there
+ * are no deltas in this event.
*
- * @return all extension deltas
+ * @return all extension deltas
*/
public IExtensionDelta[] getExtensionDeltas();
/**
- * Returns all extension deltas for the given namespace. Returns an empty array if there are
- * no deltas in this event for any extension points provided in the given namespace.
+ * Returns all extension deltas for the given namespace. Returns an empty array
+ * if there are no deltas in this event for any extension points provided in the
+ * given namespace.
*
* @param namespace the namespace for the extension deltas
* @return all extension deltas for the given namespace
@@ -44,12 +47,13 @@ public interface IRegistryChangeEvent {
public IExtensionDelta[] getExtensionDeltas(String namespace);
/**
- * Returns all the extension deltas for the given namespace and extension point. Returns an
- * empty array if there are no deltas in this event for the given extension point.
+ * Returns all the extension deltas for the given namespace and extension point.
+ * Returns an empty array if there are no deltas in this event for the given
+ * extension point.
*
- * @param namespace the namespace for the extension point
- * @param extensionPoint the simple identifier of the
- * extension point (e.g. "builders"
)
+ * @param namespace the namespace for the extension point
+ * @param extensionPoint the simple identifier of the extension point (e.g.
+ * "builders"
)
* @return all extension deltas for the given extension point
*/
public IExtensionDelta[] getExtensionDeltas(String namespace, String extensionPoint);
@@ -58,10 +62,10 @@ public interface IRegistryChangeEvent {
* Returns the delta for the given namespace, extension point and extension.
* Returns null
if none exists in this event.
*
- * @param namespace the namespace for the extension point
- * @param extensionPoint the simple identifier of the
- * extension point (e.g. "builders"
)
- * @param extension the unique identifier of the extension
+ * @param namespace the namespace for the extension point
+ * @param extensionPoint the simple identifier of the extension point (e.g.
+ * "builders"
)
+ * @param extension the unique identifier of the extension
* @return the extension delta, or null
*/
public IExtensionDelta getExtensionDelta(String namespace, String extensionPoint, String extension);
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeListener.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeListener.java
index 2e3a661e27f..b3d2ac35214 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeListener.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryChangeListener.java
@@ -16,14 +16,17 @@
import java.util.EventListener;
/**
- * Note: for new implementations consider using {@link IRegistryEventListener}.
+ * Note: for new implementations consider using
+ * {@link IRegistryEventListener}.
*
* A registry change listener is notified of changes to extensions points in the
- * registry. These changes arise from subsequent manipulation of the registry after
- * it was initially created.
- *
+ * registry. These changes arise from subsequent manipulation of the registry
+ * after it was initially created.
+ *
+ *
* This interface can be used without OSGi running.
- *
+ *
+ *
* Clients may implement this interface.
*
*
@@ -36,11 +39,12 @@ public interface IRegistryChangeListener extends EventListener {
* Notifies this listener that some registry changes are happening, or have
* already happened.
*
- * The supplied event gives details. This event object (and the deltas in it) is valid
- * only for the duration of the invocation of this method.
- *
- * Note: This method is called by the platform; it is not intended
- * to be called directly by clients.
+ * The supplied event gives details. This event object (and the deltas in it) is
+ * valid only for the duration of the invocation of this method.
+ *
+ *
+ * Note: This method is called by the platform; it is not intended to be called
+ * directly by clients.
*
*
* @param event the registry change event
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryEventListener.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryEventListener.java
index 39cdc471272..1db967dfa2f 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryEventListener.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/IRegistryEventListener.java
@@ -17,14 +17,17 @@
/**
* A registry event listener is notified of changes to extension points. Changes
- * include modifications of extension points and their extensions. Listeners will
- * only receive a notification if the extension point they are registered for is
- * modified. (Which includes modifications of extensions under the extension point.)
+ * include modifications of extension points and their extensions. Listeners
+ * will only receive a notification if the extension point they are registered
+ * for is modified. (Which includes modifications of extensions under the
+ * extension point.)
*
* This interface can be used without OSGi running.
- *
+ *
+ *
* Clients may implement this interface.
*
+ *
* @see IExtensionRegistry#addListener(IRegistryEventListener, String)
* @since 3.4
*/
@@ -33,9 +36,10 @@ public interface IRegistryEventListener extends EventListener {
/**
* Notifies this listener that extensions were added to the registry.
*
- * The extensions supplied as the argument are valid only for the duration of the
- * invocation of this method.
+ * The extensions supplied as the argument are valid only for the duration of
+ * the invocation of this method.
*
+ *
* @param extensions extensions added to the registry
*/
public void added(IExtension[] extensions);
@@ -43,9 +47,10 @@ public interface IRegistryEventListener extends EventListener {
/**
* Notifies this listener that extensions were removed from the registry.
*
- * The extensions supplied as the argument are valid only for the duration of the
- * invocation of this method.
+ * The extensions supplied as the argument are valid only for the duration of
+ * the invocation of this method.
*
+ *
* @param extensions extensions removed from the registry
*/
public void removed(IExtension[] extensions);
@@ -53,9 +58,10 @@ public interface IRegistryEventListener extends EventListener {
/**
* Notifies this listener that extension points were added to the registry.
*
- * The extension points supplied as the argument are valid only for the duration of the
- * invocation of this method.
+ * The extension points supplied as the argument are valid only for the duration
+ * of the invocation of this method.
*
+ *
* @param extensionPoints extension points added to the registry
*/
public void added(IExtensionPoint[] extensionPoints);
@@ -63,9 +69,10 @@ public interface IRegistryEventListener extends EventListener {
/**
* Notifies this listener that extension points were removed from the registry.
*
- * The extension points supplied as the argument are valid only for the duration of the
- * invocation of this method.
+ * The extension points supplied as the argument are valid only for the duration
+ * of the invocation of this method.
*
+ *
* @param extensionPoints extension points removed from the registry
*/
public void removed(IExtensionPoint[] extensionPoints);
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/InvalidRegistryObjectException.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/InvalidRegistryObjectException.java
index 85e854afacc..b34e738f27c 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/InvalidRegistryObjectException.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/InvalidRegistryObjectException.java
@@ -14,15 +14,16 @@
package org.eclipse.core.runtime;
/**
- * An unchecked exception indicating that an attempt to access
- * an extension registry object that is no longer valid.
+ * An unchecked exception indicating that an attempt to access an extension
+ * registry object that is no longer valid.
+ *
+ * This exception is thrown by methods on extension registry objects. It is not
+ * intended to be instantiated or subclassed by clients.
+ *
*
- * This exception is thrown by methods on extension registry
- * objects. It is not intended to be instantiated or
- * subclassed by clients.
- *
* This class can be used without OSGi running.
*
+ *
* @noinstantiate This class is not intended to be instantiated by clients.
* @noextend This class is not intended to be subclassed by clients.
*/
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/RegistryFactory.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/RegistryFactory.java
index 6000c424449..e2cb7052350 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/RegistryFactory.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/RegistryFactory.java
@@ -24,13 +24,16 @@
* Use this class to create or obtain an extension registry.
*
* The following methods can be used without OSGi running:
- *
+ *
+ *
* - {@link #createRegistry(RegistryStrategy, Object, Object)}
* - {@link #getRegistry()}
* - {@link #setDefaultRegistryProvider(IRegistryProvider)}
- *
+ *
+ *
* This class is not intended to be subclassed or instantiated.
*
+ *
* @since org.eclipse.equinox.registry 3.2
* @noinstantiate This class is not intended to be instantiated by clients.
*/
@@ -39,22 +42,27 @@ public final class RegistryFactory {
/**
* Creates a new extension registry based on the given set of parameters.
*
- * The strategy is an optional collection of methods that supply additional registry
- * functionality. Users may pass in null
for the strategy if default
- * behavior is sufficient.
- *
- * The master token is stored by the registry and later used as an identifier of callers
- * who are allowed full control over the registry functionality. Users may pass in
- * null
as a master token.
- *
- * The user token is stored by the registry and later used as an identifier of callers
- * who are allowed to control registry at the user level. For instance, users attempting to
- * modify dynamic contributions to the registry have to use the user token. Users may pass
- * in null
as a user token.
+ * The strategy is an optional collection of methods that supply additional
+ * registry functionality. Users may pass in null
for the strategy
+ * if default behavior is sufficient.
+ *
+ *
+ * The master token is stored by the registry and later used as an identifier of
+ * callers who are allowed full control over the registry functionality. Users
+ * may pass in null
as a master token.
+ *
+ *
+ * The user token is stored by the registry and later used as an identifier of
+ * callers who are allowed to control registry at the user level. For instance,
+ * users attempting to modify dynamic contributions to the registry have to use
+ * the user token. Users may pass in null
as a user token.
*
- * @param strategy registry strategy or null
- * @param masterToken the token used for master control of the registry or null
- * @param userToken the token used for user control of the registry or null
+ *
+ * @param strategy registry strategy or null
+ * @param masterToken the token used for master control of the registry or
+ * null
+ * @param userToken the token used for user control of the registry or
+ * null
* @return the new extension registry
*/
public static IExtensionRegistry createRegistry(RegistryStrategy strategy, Object masterToken, Object userToken) {
@@ -76,28 +84,34 @@ public static IExtensionRegistry getRegistry() {
}
/**
- * Creates a registry strategy that can be used in an OSGi container. The strategy uses
- * OSGi contributions and contributors for the registry processing and takes advantage of
- * additional mechanisms available through the OSGi library.
+ * Creates a registry strategy that can be used in an OSGi container. The
+ * strategy uses OSGi contributions and contributors for the registry processing
+ * and takes advantage of additional mechanisms available through the OSGi
+ * library.
+ *
+ * The OSGi registry strategy sequentially checks the array of storage
+ * directories to discover the location of the registry cache formed by previous
+ * invocations of the extension registry. Once found, the location is used to
+ * store registry cache. If this value is null
then caching of the
+ * registry content is disabled.
+ *
*
- * The OSGi registry strategy sequentially checks the array of storage directories to
- * discover the location of the registry cache formed by previous invocations of the extension
- * registry. Once found, the location is used to store registry cache. If this value
- * is null
then caching of the registry content is disabled.
- *
- * The cache read-only array is an array the same length as the storage directory array.
- * It contains boolean values indicating whether or not each storage directory is read-only.
- * If the value at an index is true
then the location at the corresponding index
- * in the storage directories array is read-only; if false
then the cache location
- * is read-write. The array can be null
if the storageDirs
parameter
+ * The cache read-only array is an array the same length as the storage
+ * directory array. It contains boolean values indicating whether or not each
+ * storage directory is read-only. If the value at an index is true
+ * then the location at the corresponding index in the storage directories array
+ * is read-only; if false
then the cache location is read-write.
+ * The array can be null
if the storageDirs
parameter
* is null
.
- *
- * The master token should be passed to the OSGi registry strategy to permit it to perform
- * contributions to the registry.
*
- * @param storageDirs array of file system directories or null
+ *
+ * The master token should be passed to the OSGi registry strategy to permit it
+ * to perform contributions to the registry.
+ *
+ *
+ * @param storageDirs array of file system directories or null
* @param cacheReadOnly array of read only attributes or null
- * @param token control token for the registry
+ * @param token control token for the registry
* @return registry strategy that can be used in an OSGi container
* @see #createRegistry(RegistryStrategy, Object, Object)
*/
@@ -106,15 +120,18 @@ public static RegistryStrategy createOSGiStrategy(File[] storageDirs, boolean[]
}
/**
- * Use this method to specify the default registry provider. The default registry provider
- * is immutable in the sense that it can be set only once during the application runtime.
- * Attempts to change the default registry provider will cause an exception to be thrown.
+ * Use this method to specify the default registry provider. The default
+ * registry provider is immutable in the sense that it can be set only once
+ * during the application runtime. Attempts to change the default registry
+ * provider will cause an exception to be thrown.
*
* The given registry provider must not be null
.
*
+ *
* @see RegistryFactory#getRegistry()
* @param provider extension registry provider
- * @throws CoreException if a default registry provider was already set for this application
+ * @throws CoreException if a default registry provider was already set for this
+ * application
*/
public static void setDefaultRegistryProvider(IRegistryProvider provider) throws CoreException {
RegistryProviderFactory.setDefault(provider);
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/ExtensionTracker.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/ExtensionTracker.java
index c36520ad2d3..2f140217e6a 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/ExtensionTracker.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/ExtensionTracker.java
@@ -26,11 +26,13 @@
*
* This class can be used without OSGi running.
*
+ *
* @see org.eclipse.core.runtime.dynamichelpers.IExtensionTracker
* @since 3.1
*/
public class ExtensionTracker implements IExtensionTracker, IRegistryChangeListener {
- //Map keeping the association between extensions and a set of objects. Key: IExtension, value: ReferenceHashSet.
+ // Map keeping the association between extensions and a set of objects. Key:
+ // IExtension, value: ReferenceHashSet.
private Map> extensionToObjects = new HashMap<>();
private ListenerList handlers = new ListenerList<>();
private final Object lock = new Object();
@@ -58,11 +60,17 @@ public ExtensionTracker(IExtensionRegistry theRegistry) {
if (registry != null)
registry.addRegistryChangeListener(this);
else
- RuntimeLog.log(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, 0, RegistryMessages.registry_no_default, null));
+ RuntimeLog.log(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, 0,
+ RegistryMessages.registry_no_default, null));
}
- /* (non-Javadoc)
- * @see org.eclipse.core.runtime.dynamichelpers.IExtensionTracker#registerHandler(org.eclipse.core.runtime.dynamichelpers.IExtensionChangeHandler, org.eclipse.core.runtime.dynamichelpers.IFilter)
+ /*
+ * (non-Javadoc)
+ *
+ * @see
+ * org.eclipse.core.runtime.dynamichelpers.IExtensionTracker#registerHandler(org
+ * .eclipse.core.runtime.dynamichelpers.IExtensionChangeHandler,
+ * org.eclipse.core.runtime.dynamichelpers.IFilter)
*/
@Override
public void registerHandler(IExtensionChangeHandler handler, IFilter filter) {
@@ -74,7 +82,9 @@ public void registerHandler(IExtensionChangeHandler handler, IFilter filter) {
}
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see IExtensionTracker@unregisterHandler(IExtensionChangeHandler)
*/
@Override
@@ -86,7 +96,9 @@ public void unregisterHandler(IExtensionChangeHandler handler) {
}
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see IExtensionTracker@registerObject(IExtension, Object, int)
*/
@Override
@@ -119,24 +131,24 @@ public void registryChanged(IRegistryChangeEvent event) {
int len = delta.length;
for (int i = 0; i < len; i++)
switch (delta[i].getKind()) {
- case IExtensionDelta.ADDED :
- doAdd(delta[i]);
- break;
- case IExtensionDelta.REMOVED :
- doRemove(delta[i]);
- break;
- default :
- break;
+ case IExtensionDelta.ADDED:
+ doAdd(delta[i]);
+ break;
+ case IExtensionDelta.REMOVED:
+ doRemove(delta[i]);
+ break;
+ default:
+ break;
}
}
/**
- * Notify all handlers whose filter matches that the given delta occurred.
- * If the list of objects is not null
then this is a removal and
- * the handlers will be given a chance to process the list. If it is null
- * then the notification is an addition.
+ * Notify all handlers whose filter matches that the given delta occurred. If
+ * the list of objects is not null
then this is a removal and the
+ * handlers will be given a chance to process the list. If it is
+ * null
then the notification is an addition.
*
- * @param delta the change to broadcast
+ * @param delta the change to broadcast
* @param objects the objects to pass to the handlers on removals
*/
private void notify(IExtensionDelta delta, Object[] objects) {
@@ -180,7 +192,7 @@ private void doRemove(IExtensionDelta delta) {
if (associatedObjects == null)
removedObjects = EMPTY_ARRAY;
else
- //Copy the objects early so we don't hold the lock too long
+ // Copy the objects early so we don't hold the lock too long
removedObjects = associatedObjects.toArray();
}
notify(delta, removedObjects);
@@ -190,7 +202,9 @@ protected void applyRemove(IExtensionChangeHandler handler, IExtension removedEx
handler.removeExtension(removedExtension, removedObjects);
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see IExtensionTracker@getObjects(IExtension)
*/
@Override
@@ -206,7 +220,9 @@ public Object[] getObjects(IExtension element) {
}
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see IExtensionTracker@close()
*/
@Override
@@ -223,7 +239,9 @@ public void close() {
}
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see IExtensionTracker@unregisterObject(IExtension, Object)
*/
@Override
@@ -237,7 +255,9 @@ public void unregisterObject(IExtension extension, Object object) {
}
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see IExtensionTracker@unregisterObject(IExtension)
*/
@Override
@@ -253,7 +273,8 @@ public Object[] unregisterObject(IExtension extension) {
}
/**
- * Return an instance of filter matching all changes for the given extension point.
+ * Return an instance of filter matching all changes for the given extension
+ * point.
*
* @param xpt the extension point
* @return a filter
@@ -263,7 +284,8 @@ public static IFilter createExtensionPointFilter(final IExtensionPoint xpt) {
}
/**
- * Return an instance of filter matching all changes for the given extension points.
+ * Return an instance of filter matching all changes for the given extension
+ * points.
*
* @param xpts the extension points used to filter
* @return a filter
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionChangeHandler.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionChangeHandler.java
index 5d6c5a80705..2a0f7686d73 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionChangeHandler.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionChangeHandler.java
@@ -16,23 +16,25 @@
import org.eclipse.core.runtime.IExtension;
/**
- * Extension change handlers are notified of changes for a given extension
- * point in the context of an extension tracker.
+ * Extension change handlers are notified of changes for a given extension point
+ * in the context of an extension tracker.
*
* This interface can be used without OSGi running.
- *
+ *
+ *
* This interface is intended to be implemented by clients.
*
+ *
* @since 3.1
*/
public interface IExtensionChangeHandler {
/**
- * This method is called whenever an extension conforming to the extension point filter
- * is being added to the registry. This method does not automatically register objects
- * to the tracker.
+ * This method is called whenever an extension conforming to the extension point
+ * filter is being added to the registry. This method does not automatically
+ * register objects to the tracker.
*
- * @param tracker a tracker to which the handler has been registered
+ * @param tracker a tracker to which the handler has been registered
* @param extension the extension being added
*/
public void addExtension(IExtensionTracker tracker, IExtension extension);
@@ -41,7 +43,7 @@ public interface IExtensionChangeHandler {
* This method is called after the removal of an extension.
*
* @param extension the extension being removed
- * @param objects the objects that were associated with the removed extension
+ * @param objects the objects that were associated with the removed extension
*/
public void removeExtension(IExtension extension, Object[] objects);
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionTracker.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionTracker.java
index a75c47d58c5..eb2049fd8b2 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionTracker.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IExtensionTracker.java
@@ -17,14 +17,18 @@
import org.eclipse.core.runtime.IExtension;
/**
- * An extension tracker keeps associations between extensions and their derived objects on an extension basis.
- * All extensions being added in a tracker will automatically be removed when the extension is uninstalled from the registry.
- * Users interested in extension removal can register a handler that will let them know when an object is being removed.
+ * An extension tracker keeps associations between extensions and their derived
+ * objects on an extension basis. All extensions being added in a tracker will
+ * automatically be removed when the extension is uninstalled from the registry.
+ * Users interested in extension removal can register a handler that will let
+ * them know when an object is being removed.
*
* This interface can be used without OSGi running.
- *
+ *
+ *
* This interface is not intended to be implemented by clients.
*
+ *
* @since 3.1
* @noimplement This interface is not intended to be implemented by clients.
*/
@@ -52,27 +56,30 @@ public interface IExtensionTracker {
public static final int REF_WEAK = ReferenceHashSet.WEAK;
/**
- * Register an extension change handler with this tracker using the given filter.
+ * Register an extension change handler with this tracker using the given
+ * filter.
*
* @param handler the handler to be registered
- * @param filter the filter to use to choose interesting changes
+ * @param filter the filter to use to choose interesting changes
*/
public void registerHandler(IExtensionChangeHandler handler, IFilter filter);
/**
- * Unregister the given extension change handler previously registered with this tracker.
+ * Unregister the given extension change handler previously registered with this
+ * tracker.
*
* @param handler the handler to be unregistered
*/
public void unregisterHandler(IExtensionChangeHandler handler);
/**
- * Create an association between the given extension and the given object.
- * The referenceType indicates how strongly the object is being kept in memory.
- * There is 3 possible values: {@link #REF_STRONG}, {@link #REF_SOFT}, {@link #REF_WEAK}.
+ * Create an association between the given extension and the given object. The
+ * referenceType indicates how strongly the object is being kept in memory.
+ * There is 3 possible values: {@link #REF_STRONG}, {@link #REF_SOFT},
+ * {@link #REF_WEAK}.
*
- * @param extension the extension
- * @param object the object to associate with the extension
+ * @param extension the extension
+ * @param object the object to associate with the extension
* @param referenceType one of REF_STRONG, REF_SOFT, REF_WEAK
* @see #REF_STRONG
* @see #REF_SOFT
@@ -84,13 +91,13 @@ public interface IExtensionTracker {
* Remove an association between the given extension and the given object.
*
* @param extension the extension under which the object has been registered
- * @param object the object to unregister
+ * @param object the object to unregister
*/
public void unregisterObject(IExtension extension, Object object);
/**
- * Remove all the objects associated with the given extension. Return
- * the removed objects.
+ * Remove all the objects associated with the given extension. Return the
+ * removed objects.
*
* @param extension the extension for which the objects are removed
* @return the objects that were associated with the extension
@@ -99,9 +106,10 @@ public interface IExtensionTracker {
/**
* Return all the objects that have been associated with the given extension.
- * All objects registered strongly will be return unless they have been unregistered.
- * The objects registered softly or weakly may not be returned if they have been garbage collected.
- * Return an empty array if no associations exist.
+ * All objects registered strongly will be return unless they have been
+ * unregistered. The objects registered softly or weakly may not be returned if
+ * they have been garbage collected. Return an empty array if no associations
+ * exist.
*
* @param extension the extension for which the object must be returned
* @return the array of associated objects
@@ -109,7 +117,8 @@ public interface IExtensionTracker {
public Object[] getObjects(IExtension extension);
/**
- * Close the tracker. All registered objects are freed and all handlers are being automatically removed.
+ * Close the tracker. All registered objects are freed and all handlers are
+ * being automatically removed.
*/
public void close();
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IFilter.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IFilter.java
index 8b9e692c4fc..0b7756046f9 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IFilter.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/dynamichelpers/IFilter.java
@@ -21,19 +21,21 @@
*
* This interface may be implemented by clients, however factory methods are
* available on IExtensionTracker.
- *
+ *
+ *
* This interface can be used without OSGi running.
*
+ *
* @since 3.1
*/
public interface IFilter {
/**
- * Return true
if the given object matches the criteria
- * for this filter.
+ * Return true
if the given object matches the criteria for this
+ * filter.
*
* @param target the object to match
- * @return true
if the target matches this filter
- * and false
otherwise
+ * @return true
if the target matches this filter and
+ * false
otherwise
*/
public boolean matches(IExtensionPoint target);
}
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IDynamicExtensionRegistry.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IDynamicExtensionRegistry.java
index 5915a5da00d..569c51164d2 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IDynamicExtensionRegistry.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IDynamicExtensionRegistry.java
@@ -16,24 +16,29 @@
import org.eclipse.core.runtime.IContributor;
/**
- * This interface provides an extra degree of access to an extension registry that
- * might be useful to registry implementers.
+ * This interface provides an extra degree of access to an extension registry
+ * that might be useful to registry implementers.
+ *
+ * At this time functionality available through this interface is not intended
+ * to be used with the default Eclipse extension registry.
+ *
+ *
+ * Note: This class/interface is part of an interim SPI that is still
+ * under development and expected to change significantly before reaching
+ * stability. It is being made available at this early stage to solicit feedback
+ * from pioneering adopters on the understanding that any code that uses this
+ * SPI will almost certainly be broken (repeatedly) as the SPI evolves.
+ *
*
- * At this time functionality available through this interface is not intended to
- * be used with the default Eclipse extension registry.
- *
- * Note: This class/interface is part of an interim SPI that is still under
- * development and expected to change significantly before reaching stability.
- * It is being made available at this early stage to solicit feedback from pioneering
- * adopters on the understanding that any code that uses this SPI will almost certainly
- * be broken (repeatedly) as the SPI evolves.
- *
* This interface is not intended to be extended by clients.
- *
+ *
+ *
* This interface should not be implemented by clients.
- *
+ *
+ *
* This interface can be used without OSGi running.
*
+ *
* @since 3.4
* @noextend This interface is not intended to be extended by clients.
* @noimplement This interface is not intended to be implemented by clients.
@@ -43,17 +48,20 @@ public interface IDynamicExtensionRegistry {
/**
* Removes all extensions and extension points provided by the contributor.
*
- * This method is an access controlled method. Access tokens are specified when the registry
- * is constructed by the registry implementers.
+ * This method is an access controlled method. Access tokens are specified when
+ * the registry is constructed by the registry implementers.
*
- * @see org.eclipse.core.runtime.RegistryFactory#createRegistry(RegistryStrategy, Object, Object)
+ *
+ * @see org.eclipse.core.runtime.RegistryFactory#createRegistry(RegistryStrategy,
+ * Object, Object)
* @param contributor the contributor to be removed
- * @param key registry access key
+ * @param key registry access key
*/
public void removeContributor(IContributor contributor, Object key);
/**
* Finds out if registry has the contributor.
+ *
* @param contributor registry contributor
* @return true if the registry has this contributor; false otherwise
*/
@@ -61,6 +69,7 @@ public interface IDynamicExtensionRegistry {
/**
* Returns all contributors associated with the registry at this time.
+ *
* @return all contributors associated with the registry
*/
public IContributor[] getAllContributors();
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IRegistryProvider.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IRegistryProvider.java
index 3618f6d27b8..14be3dad7bb 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IRegistryProvider.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/IRegistryProvider.java
@@ -19,9 +19,11 @@
* Implement this interface to specify a contributed extension registry.
*
* This interface can be used without OSGi running.
- *
+ *
+ *
* This interface may be implemented by clients.
*
+ *
* @see org.eclipse.core.runtime.RegistryFactory#getRegistry()
* @see org.eclipse.core.runtime.RegistryFactory#setDefaultRegistryProvider(IRegistryProvider)
* @since org.eclipse.equinox.registry 3.2
@@ -29,8 +31,8 @@
public interface IRegistryProvider {
/**
- * Returns the extension registry contributed by this provider; must not
- * be null
.
+ * Returns the extension registry contributed by this provider; must not be
+ * null
.
*
* @return an extension registry
*/
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryContributor.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryContributor.java
index 232d49c8f2d..2220a965859 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryContributor.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryContributor.java
@@ -16,24 +16,29 @@
import org.eclipse.core.runtime.IContributor;
/**
- * This class describes a registry contributor which is an entity that supplies information
- * to the extension registry. Depending on the registry strategy, contributor might delegate
- * some of its functionality to a "host" contributor. For instance, OSGi registry strategy
- * uses "host" contributor to delegate some functionality from fragments to plug-ins.
+ * This class describes a registry contributor which is an entity that supplies
+ * information to the extension registry. Depending on the registry strategy,
+ * contributor might delegate some of its functionality to a "host" contributor.
+ * For instance, OSGi registry strategy uses "host" contributor to delegate some
+ * functionality from fragments to plug-ins.
*
* This class can be instantiated by the registry Service Providers.
- *
+ *
+ *
* This class can be used without OSGi running.
- *
+ *
+ *
* This class can not be extended.
*
+ *
* @since org.eclipse.equinox.registry 3.2
* @noextend This class is not intended to be subclassed by clients.
*/
public final class RegistryContributor implements IContributor {
/**
- * Actual ID of the contributor (e.g., "12"). IDs are expected to be unique in the workspace.
+ * Actual ID of the contributor (e.g., "12"). IDs are expected to be unique in
+ * the workspace.
*/
private String actualContributorId;
@@ -43,47 +48,53 @@ public final class RegistryContributor implements IContributor {
private String actualContributorName;
/**
- * ID associated with the entity "in charge" of the contributor (e.g., "1"). IDs are expected
- * to be unique in the workspace. If contributor does not rely on a host, this value should be
- * the same as the actual contributor ID.
+ * ID associated with the entity "in charge" of the contributor (e.g., "1"). IDs
+ * are expected to be unique in the workspace. If contributor does not rely on a
+ * host, this value should be the same as the actual contributor ID.
*/
private String hostId;
/**
- * Name of the entity "in charge" of the contributor (e.g. "org.eclipse.core.runtime").
- * If contributor does not rely on a host, this value should be the same as the actual
- * contributor name.
+ * Name of the entity "in charge" of the contributor (e.g.
+ * "org.eclipse.core.runtime"). If contributor does not rely on a host, this
+ * value should be the same as the actual contributor name.
*/
private String hostName;
/**
* Constructor for the registry contributor.
*
- * The actual ID is a string identifier for the contributor (e.g., "12") and is expected
- * to be unique within the workspace. The actual ID of the contributor must not
- * be null
.
- *
- * The actual name is the name associated with the contributor
- * (e.g., "org.eclipse.core.runtime.fragment"). The actual name of the contributor must
+ * The actual ID is a string identifier for the contributor (e.g., "12") and is
+ * expected to be unique within the workspace. The actual ID of the contributor
+ * must not be null
.
+ *
+ *
+ * The actual name is the name associated with the contributor (e.g.,
+ * "org.eclipse.core.runtime.fragment"). The actual name of the contributor must
* not be null
.
- *
- * The host ID is the identifier associated with the entity "in charge" of the contributor
- * (e.g., "1"). IDs are expected to be unique in the workspace. If contributor does not
- * rely on a host, then null
should be used as the host ID.
- *
- * The host name is the name of the entity "in charge" of the contributor
- * (e.g., "org.eclipse.core.runtime"). If contributor does not rely on a host, then
+ *
+ *
+ * The host ID is the identifier associated with the entity "in charge" of the
+ * contributor (e.g., "1"). IDs are expected to be unique in the workspace. If
+ * contributor does not rely on a host, then null
should be used as
+ * the host ID.
+ *
+ *
+ * The host name is the name of the entity "in charge" of the contributor (e.g.,
+ * "org.eclipse.core.runtime"). If contributor does not rely on a host, then
* null
should be used as the host name.
- *
+ *
+ *
* There should be 1-to-1 mapping between the contributor and the contibutor ID.
- * The IDs (either actual or host) can not be re-used in the same registry.
- * For example, if ID of 12 was used to identify contributorA, the ID of 12 can not
+ * The IDs (either actual or host) can not be re-used in the same registry. For
+ * example, if ID of 12 was used to identify contributorA, the ID of 12 can not
* be used to identify contributorB or a host for the contributorC.
*
- * @param actualId contributor identifier
+ *
+ * @param actualId contributor identifier
* @param actualName name of the contributor
- * @param hostId id associated with the host, or null
- * @param hostName name of the host, or null
+ * @param hostId id associated with the host, or null
+ * @param hostName name of the host, or null
*/
public RegistryContributor(String actualId, String actualName, String hostId, String hostName) {
this.actualContributorId = actualId;
@@ -98,8 +109,8 @@ public RegistryContributor(String actualId, String actualName, String hostId, St
}
/**
- * Provides actual ID associated with the registry contributor (e.g., "12"). IDs are expected
- * to be unique in the workspace.
+ * Provides actual ID associated with the registry contributor (e.g., "12"). IDs
+ * are expected to be unique in the workspace.
*
* @return actual ID of the registry contributor
*/
@@ -108,7 +119,8 @@ public String getActualId() {
}
/**
- * Provides actual name of the registry contributor (e.g., "org.eclipe.core.runtime.fragment").
+ * Provides actual name of the registry contributor (e.g.,
+ * "org.eclipe.core.runtime.fragment").
*
* @return actual name of the registry contributor
*/
@@ -117,9 +129,9 @@ public String getActualName() {
}
/**
- * Provides ID associated with the entity "in charge" of the contributor (e.g., "1"). IDs are expected
- * to be unique in the workspace. If contributor does not rely on a host, this value should be
- * the same as the actual contributor ID.
+ * Provides ID associated with the entity "in charge" of the contributor (e.g.,
+ * "1"). IDs are expected to be unique in the workspace. If contributor does not
+ * rely on a host, this value should be the same as the actual contributor ID.
*
* @return id of the registry contributor
*/
@@ -128,8 +140,9 @@ public String getId() {
}
/**
- * Provides name of the entity "in charge" of the contributor (e.g., "org.eclipse.core.runtime").
- * If contributor does not rely on a host, this value should be the same as the actual contributor name.
+ * Provides name of the entity "in charge" of the contributor (e.g.,
+ * "org.eclipse.core.runtime"). If contributor does not rely on a host, this
+ * value should be the same as the actual contributor name.
*
* @return name of the registry contributor
*/
@@ -138,7 +151,9 @@ public String getName() {
return hostName;
}
- /* (non-Javadoc)
+ /*
+ * (non-Javadoc)
+ *
* @see java.lang.Object#toString()
*/
@Override
diff --git a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryStrategy.java b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryStrategy.java
index 255c8f3d2fd..dfa30fec9d9 100644
--- a/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryStrategy.java
+++ b/bundles/org.eclipse.equinox.registry/src/org/eclipse/core/runtime/spi/RegistryStrategy.java
@@ -21,21 +21,26 @@
import org.eclipse.osgi.util.NLS;
/**
- * This is the basic registry strategy. It describes how the registry does logging,
- * message translation, extra start/stop processing, event scheduling, caching,
- * and debugging.
+ * This is the basic registry strategy. It describes how the registry does
+ * logging, message translation, extra start/stop processing, event scheduling,
+ * caching, and debugging.
*
* In this strategy:
- *
+ *
+ *
* - Logging is done onto
System.out
;
- * - The translation routine assumes that keys are prefixed with
'%'/
;
+ * - The translation routine assumes that keys are prefixed with
+ *
'%'/
;
* - Caching is enabled and doesn't use state or time stamp validation;
* - Standard Java class loading is used to create executable extensions.
- *
+ *
+ *
* This class can be used without OSGi running.
- *
+ *
+ *
* This class can be overridden and/or instantiated by clients.
*
+ *
* @since org.eclipse.equinox.registry 3.2
*/
public class RegistryStrategy {
@@ -43,7 +48,8 @@ public class RegistryStrategy {
private SAXParserFactory theXMLParserFactory = null;
/**
- * Array of file system directories to store cache files; might be null
+ * Array of file system directories to store cache files; might be
+ * null
*/
private final File[] storageDirs;
@@ -55,20 +61,23 @@ public class RegistryStrategy {
/**
* Constructor for this default registry strategy.
*
- * The strategy sequentially checks the array of storage directories to
- * discover the location of the registry cache formed by previous invocations of the extension
- * registry. Once found, the location is used to store registry cache. If this value
- * is null
then caching of the registry content is disabled.
- *
- * The cache read-only array is an array the same length as the storage directory array.
- * It contains boolean values indicating whether or not each storage directory is read-only.
- * If the value at an index is true
then the location at the corresponding index
- * in the storage directories array is read-only; if false
then the cache location
- * is read-write. The array can be null
if the storageDirs
parameter
+ * The strategy sequentially checks the array of storage directories to discover
+ * the location of the registry cache formed by previous invocations of the
+ * extension registry. Once found, the location is used to store registry cache.
+ * If this value is null
then caching of the registry content is
+ * disabled.
+ *
+ *
+ * The cache read-only array is an array the same length as the storage
+ * directory array. It contains boolean values indicating whether or not each
+ * storage directory is read-only. If the value at an index is true
+ * then the location at the corresponding index in the storage directories array
+ * is read-only; if false
then the cache location is read-write.
+ * The array can be null
if the storageDirs
parameter
* is null
.
*
*
- * @param storageDirs array of file system directories, or null
+ * @param storageDirs array of file system directories, or null
* @param cacheReadOnly array of read only attributes, or null
*/
public RegistryStrategy(File[] storageDirs, boolean[] cacheReadOnly) {
@@ -103,8 +112,8 @@ public final File getStorage(int index) {
* Returns the read-only status of the registry cache location.
*
* @param index the index of the possible registry location
- * @return true
if the location is read only and
- * false
if the location is read/write
+ * @return true
if the location is read only and false
+ * if the location is read/write
*/
public final boolean isCacheReadOnly(int index) {
if (cacheReadOnly != null)
@@ -113,11 +122,13 @@ public final boolean isCacheReadOnly(int index) {
}
/**
- * Override this method to provide customized logging functionality
- * to the registry. The method adds a log entry based on the supplied status.
+ * Override this method to provide customized logging functionality to the
+ * registry. The method adds a log entry based on the supplied status.
*
- * This method writes a message to System.out
- * in the following format:
+ * This method writes a message to System.out
in the following
+ * format:
+ *
+ *
*
* [Error|Warning|Log]: Main error message
* [Error|Warning|Log]: Child error message 1
@@ -136,11 +147,11 @@ public void log(IStatus status) {
* optional and might be null
.
*
* The default translation routine assumes that keys are prefixed with '%'. If
- * no resource bundle is present, the key itself (without leading '%') is returned.
- * There is no decoding for the leading '%%'.
+ * no resource bundle is present, the key itself (without leading '%') is
+ * returned. There is no decoding for the leading '%%'.
*
*
- * @param key message key to be translated
+ * @param key message key to be translated
* @param resources resource bundle, or null
* @return the translated string, must not be null
*/
@@ -149,14 +160,15 @@ public String translate(String key, ResourceBundle resources) {
}
/**
- * Override this method to provide additional processing performed
- * when the registry is created and started. Overrides should call
+ * Override this method to provide additional processing performed when the
+ * registry is created and started. Overrides should call
* super.onStart()
at the beginning of the processing.
*
- * NOTE: Avoid placing duplicate functionality in
- * this method and {@link #onStart(IExtensionRegistry, boolean)} as
- * both methods will be called on the registry startup.
+ * NOTE: Avoid placing duplicate functionality in this method
+ * and {@link #onStart(IExtensionRegistry, boolean)} as both methods will be
+ * called on the registry startup.
*
+ *
* @param registry the extension registry being started
*
* @deprecated use {@link #onStart(IExtensionRegistry, boolean)}.
@@ -167,13 +179,13 @@ public void onStart(IExtensionRegistry registry) {
}
/**
- * Override this method to provide additional processing performed
- * when the registry is created and started. Overrides should call
+ * Override this method to provide additional processing performed when the
+ * registry is created and started. Overrides should call
* super.onStart()
at the beginning of the processing.
*
- * @param registry the extension registry being started
- * @param loadedFromCache true is registry contents was loaded from
- * cache when the registry was created
+ * @param registry the extension registry being started
+ * @param loadedFromCache true is registry contents was loaded from cache when
+ * the registry was created
*
* @since 3.4
*/
@@ -182,9 +194,10 @@ public void onStart(IExtensionRegistry registry, boolean loadedFromCache) {
}
/**
- * Override this method to provide additional processing to be performed
- * just before the registry is stopped. Overrides should call
+ * Override this method to provide additional processing to be performed just
+ * before the registry is stopped. Overrides should call
* super.onStop()
at the end of the processing.
+ *
* @param registry the extension registry being stopped
*/
public void onStop(IExtensionRegistry registry) {
@@ -192,71 +205,88 @@ public void onStop(IExtensionRegistry registry) {
}
/**
- * Creates an executable extension. Override this method to supply an alternative processing
- * for the creation of executable extensions.
+ * Creates an executable extension. Override this method to supply an
+ * alternative processing for the creation of executable extensions.
*
- * This method receives the contributor of the executable extension and, possibly,
- * an optional contributor name if specified by the executable extension. The overridden
- * contributor name might be null
.
- *
- * In this implementation registry attempts to instantiate the class specified via
- * the class name (must not be null
) using standard Java reflection mechanism.
- * This method assumes that such class has a default constructor with no arguments.
+ * This method receives the contributor of the executable extension and,
+ * possibly, an optional contributor name if specified by the executable
+ * extension. The overridden contributor name might be null
.
+ *
+ *
+ * In this implementation registry attempts to instantiate the class specified
+ * via the class name (must not be null
) using standard Java
+ * reflection mechanism. This method assumes that such class has a default
+ * constructor with no arguments.
*
*
- * @param contributor the contributor of this executable extension
- * @param className the name of the class to be instantiated
- * @param overridenContributorName the contributor to be used, or null
if not specified
+ * @param contributor the contributor of this executable extension
+ * @param className the name of the class to be instantiated
+ * @param overridenContributorName the contributor to be used, or
+ * null
if not specified
* @return the object created, or null
- * @throws CoreException if there was a problem creating the executable extension
+ * @throws CoreException if there was a problem creating the executable
+ * extension
* @see IConfigurationElement#createExecutableExtension(String)
* @see IExecutableExtension
*/
- public Object createExecutableExtension(RegistryContributor contributor, String className, String overridenContributorName) throws CoreException {
+ public Object createExecutableExtension(RegistryContributor contributor, String className,
+ String overridenContributorName) throws CoreException {
Object result = null;
Class> classInstance = null;
try {
classInstance = Class.forName(className);
} catch (ClassNotFoundException e1) {
String message = NLS.bind(RegistryMessages.exExt_findClassError, contributor.getActualName(), className);
- throw new CoreException(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, IRegistryConstants.PLUGIN_ERROR, message, e1));
+ throw new CoreException(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME,
+ IRegistryConstants.PLUGIN_ERROR, message, e1));
}
try {
result = classInstance.getDeclaredConstructor().newInstance();
} catch (Exception e) {
- String message = NLS.bind(RegistryMessages.exExt_instantiateClassError, contributor.getActualName(), className);
- throw new CoreException(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME, IRegistryConstants.PLUGIN_ERROR, message, e));
+ String message = NLS.bind(RegistryMessages.exExt_instantiateClassError, contributor.getActualName(),
+ className);
+ throw new CoreException(new Status(IStatus.ERROR, RegistryMessages.OWNER_NAME,
+ IRegistryConstants.PLUGIN_ERROR, message, e));
}
return result;
}
/**
- * Override this method to customize scheduling of an extension registry event. Note that this method
- * must make the following call to actually process the event:
- *
+ * Override this method to customize scheduling of an extension registry event.
+ * Note that this method must make the following call to
+ * actually process the event:
+ *
+ *
+ *
* RegistryStrategy.processChangeEvent(listeners, deltas, registry);
- *
- * In the default implementation, the method registry events are executed in a queue
- * on a separate thread (i.e. asynchronously, sequentially).
+ *
+ *
+ *
+ * In the default implementation, the method registry events are executed in a
+ * queue on a separate thread (i.e. asynchronously, sequentially).
*
*
- * @param listeners the list of active listeners (thread safe); may not be null
- * @param deltas the registry deltas (thread safe); may not be null
- * @param registry the extension registry (NOT thread safe); may not be null
+ * @param listeners the list of active listeners (thread safe); may not be
+ * null
+ * @param deltas the registry deltas (thread safe); may not be
+ * null
+ * @param registry the extension registry (NOT thread safe); may not be
+ * null
*/
public void scheduleChangeEvent(Object[] listeners, Map deltas, Object registry) {
((ExtensionRegistry) registry).scheduleChangeEvent(listeners, deltas);
}
/**
- * This method performs actual processing of the registry change event. It should
- * only be used by overrides of the RegistryStrategy.scheduleChangeEvent. It will
- * return null
if an unexpected registry type was encountered.
+ * This method performs actual processing of the registry change event. It
+ * should only be used by overrides of the RegistryStrategy.scheduleChangeEvent.
+ * It will return null
if an unexpected registry type was
+ * encountered.
*
* @param listeners the list of active listeners; may not be null
- * @param deltas the extension registry deltas; may not be null
- * @param registry the extension registry; may not be null
+ * @param deltas the extension registry deltas; may not be null
+ * @param registry the extension registry; may not be null
* @return status of the operation or null
*/
public final static IStatus processChangeEvent(Object[] listeners, Map deltas, Object registry) {
@@ -266,45 +296,49 @@ public final static IStatus processChangeEvent(Object[] listeners, Mapfalse
indicating that debug functionality
- * is turned off.
+ * Override this method to specify debug requirements to the registry. In the
+ * default implementation this method returns false
indicating that
+ * debug functionality is turned off.
*
- * Note that in a general case the extension registry plug-in doesn't depend on OSGI and
- * therefore cannot use Eclipse .options files to discover debug options.
+ * Note that in a general case the extension registry plug-in doesn't depend on
+ * OSGI and therefore cannot use Eclipse .options files to discover debug
+ * options.
*
*
- * @return true
if debug logging and validation should be performed and
- * false
otherwise
+ * @return true
if debug logging and validation should be performed
+ * and false
otherwise
*/
public boolean debug() {
return false;
}
/**
- * Override this method to specify debug requirements for the registry event processing.
- * In the default implementation this method returns false
indicating that
- * debug of the registry events is turned off.
+ * Override this method to specify debug requirements for the registry event
+ * processing. In the default implementation this method returns
+ * false
indicating that debug of the registry events is turned
+ * off.
*
- * Note that in a general case the extension registry plug-in doesn't depend on OSGI and
- * therefore cannot use Eclipse .options files to discover debug options.
+ * Note that in a general case the extension registry plug-in doesn't depend on
+ * OSGI and therefore cannot use Eclipse .options files to discover debug
+ * options.
*
*
- * @return true
if debug logging and validation of the registry events
- * should be performed and false
otherwise
+ * @return true
if debug logging and validation of the registry
+ * events should be performed and false
otherwise
*/
public boolean debugRegistryEvents() {
return false;
}
/**
- * Specifies if the extension registry should use cache to store registry data between
- * invocations.
+ * Specifies if the extension registry should use cache to store registry data
+ * between invocations.
*
* The default implementation enables caching returning true
.
*
*
- * @return true
if the cache should be used and false
otherwise
+ * @return true
if the cache should be used and false
+ * otherwise
*/
public boolean cacheUse() {
return true;
@@ -313,35 +347,42 @@ public boolean cacheUse() {
/**
* Specifies if lazy cache loading is used.
*
- * The default implementation specifies that lazy cache loading is going to be used
- * and therefore returns true
.
+ * The default implementation specifies that lazy cache loading is going to be
+ * used and therefore returns true
.
*
*
- * @return true
if lazy cache loading is used and false
otherwise
+ * @return true
if lazy cache loading is used and
+ * false
otherwise
*/
public boolean cacheLazyLoading() {
return true;
}
/**
- * This method is called as a part of the registry cache validation. The cache is valid
- * on the registry startup if the pair {container time stamp, contributors time stamp}
- * supplied by the registry strategy is the same as the {container time stamp, contributors time stamp}
- * stored in the registry cache. The goal of the validation is to be able to catch modifications
- * made to the original data contributed into the registry and not reflected in the registry cache.
+ * This method is called as a part of the registry cache validation. The cache
+ * is valid on the registry startup if the pair {container time stamp,
+ * contributors time stamp} supplied by the registry strategy is the same as the
+ * {container time stamp, contributors time stamp} stored in the registry cache.
+ * The goal of the validation is to be able to catch modifications made to the
+ * original data contributed into the registry and not reflected in the registry
+ * cache.
+ *
+ * The method produces a number that corresponds to the current state of the
+ * data stored by the container. Increment the stamp if the data stored in the
+ * container has been updated so that the data cached by the registry is no
+ * longer valid. For instance, in Eclipse addition or removal of a bundle
+ * results in the number returned by this method being incremented. As a result,
+ * if a bundle that contributed plugin.xml into the extension registry was
+ * modified, the state doesn't match the state stored in the registry cache. In
+ * this case the cache content becomes invalid and the registry needs to be
+ * re-created from the original data.
+ *
+ *
+ * Generally, treat this number as a hash code for the data stored in the
+ * registry. It stays the same as long as the registry content is not changing.
+ * It becomes a different number as the registry content gets modified.
+ *
*
- * The method produces a number that corresponds to the current state of the data stored
- * by the container. Increment the stamp if the data stored in the container has been updated
- * so that the data cached by the registry is no longer valid. For instance, in Eclipse addition
- * or removal of a bundle results in the number returned by this method being incremented. As a result,
- * if a bundle that contributed plugin.xml into the extension registry was modified, the state doesn't
- * match the state stored in the registry cache. In this case the cache content becomes invalid and
- * the registry needs to be re-created from the original data.
- *
- * Generally, treat this number as a hash code for the data stored in the registry.
- * It stays the same as long as the registry content is not changing. It becomes a different
- * number as the registry content gets modified.
- *
* Return 0 to indicate that state verification is not required.
*
*
@@ -352,34 +393,42 @@ public long getContainerTimestamp() {
}
/**
- * This method is called as a part of the registry cache validation. The method calculates
- * a number describing the time when the originating contributions (i.e., plugin.xml files
- * in case of the Eclipse registry) were last modified.
+ * This method is called as a part of the registry cache validation. The method
+ * calculates a number describing the time when the originating contributions
+ * (i.e., plugin.xml files in case of the Eclipse registry) were last modified.
+ *
+ * The value returned by the method is compared with the timestamp tracked by
+ * the registry. If contributions changed since they have been added to the
+ * registry (i.e., plugin.xml file was modified since the last run), the value
+ * of the {@link #getContributionsTimestamp()} will change and no longer will be
+ * the same as the value tracked by the registry. In this case the cache is
+ * considered to be invalid and the registry is going to be re-populated form
+ * scratch.
+ *
*
- * The value returned by the method is compared with the timestamp tracked by the registry.
- * If contributions changed since they have been added to the registry (i.e., plugin.xml
- * file was modified since the last run), the value of the {@link #getContributionsTimestamp()}
- * will change and no longer will be the same as the value tracked by the registry. In this case
- * the cache is considered to be invalid and the registry is going to be re-populated form scratch.
- *
- * (The word "timestamp" is used very loosely here. In this context, "timestamp" is more likely
- * to be a hash value aggregating a number of actual timestamps from the contributions.)
- *
- * This method may return 0 to indicate that no time stamp verification is required.
+ * (The word "timestamp" is used very loosely here. In this context, "timestamp"
+ * is more likely to be a hash value aggregating a number of actual timestamps
+ * from the contributions.)
*
- * @return a value corresponding to the last modification time of contributions contained
- * in the registry
+ *
+ * This method may return 0 to indicate that no time stamp verification is
+ * required.
+ *
+ *
+ * @return a value corresponding to the last modification time of contributions
+ * contained in the registry
*/
public long getContributionsTimestamp() {
return 0;
}
/**
- * Returns the parser used by the registry to parse descriptions of extension points and extensions.
- * This method must not return null
.
+ * Returns the parser used by the registry to parse descriptions of extension
+ * points and extensions. This method must not return null
.
*
* @return this strategy's parser
- * @see org.eclipse.core.runtime.IExtensionRegistry#addContribution(java.io.InputStream, IContributor, boolean, String, ResourceBundle, Object)
+ * @see org.eclipse.core.runtime.IExtensionRegistry#addContribution(java.io.InputStream,
+ * IContributor, boolean, String, ResourceBundle, Object)
*/
public SAXParserFactory getXMLParser() {
if (theXMLParserFactory == null) {
@@ -398,15 +447,17 @@ public SAXParserFactory getXMLParser() {
* Translates array of keys supplied by the contributor to the requested locale.
*
* This method is intended to be overridden by specialized registry strategies
- * that know translation conventions for the contributors, for instance,
- * the agreed upon locations of the translated keys for bundle contributors.
- * The base implementation simply returns the array of non-translated keys.
- *
+ * that know translation conventions for the contributors, for instance, the
+ * agreed upon locations of the translated keys for bundle contributors. The
+ * base implementation simply returns the array of non-translated keys.
+ *
+ *
* This method is only used if multi-language support is enabled.
*
+ *
* @param nonTranslated message keys to be translated
- * @param contributor the contributor of the keys to be translated
- * @param locale the requested locale for the keys
+ * @param contributor the contributor of the keys to be translated
+ * @param locale the requested locale for the keys
* @return the arrays of translated strings
* @see IExtensionRegistry#isMultiLanguage()
* @since org.eclipse.equinox.registry 3.5
@@ -419,17 +470,21 @@ public String[] translate(String[] nonTranslated, IContributor contributor, Stri
* Returns the current locale for the extension registry with enabled
* multi-language support.
*
- * The default implementation assumes that there is a single system wide
- * locale, equivalent to {@link Locale#getDefault()}.
- *
+ * The default implementation assumes that there is a single system wide locale,
+ * equivalent to {@link Locale#getDefault()}.
+ *
+ *
* The result of this method should not be retained or passed to other threads.
* The current locale can change any time and may be different for each thread.
- *
- * This method can be overridden by subclasses that wish to provide a way
- * to change the default locale.
- *
+ *
+ *
+ * This method can be overridden by subclasses that wish to provide a way to
+ * change the default locale.
+ *
+ *
* This method is only used if multi-language support is enabled.
*
+ *
* @see IExtensionRegistry#isMultiLanguage()
* @return the default locale
* @since org.eclipse.equinox.registry 3.5