org.eclipse.tptp.platform.probekit.registry
Class ProbeRegistry

java.lang.Object
  org.eclipse.tptp.platform.probekit.registry.ProbeRegistry

public class ProbeRegistry

extends java.lang.Object

The Probe Registry manages probe resources for query, deployment, import, and export operations. There is a probe registry for each workspace.

Entries can be made to the registry in two forms: From a zip file previously created by exporting a .probe file, or from the component pieces. The miniumum pieces include the source file (.probe file) and all files required to deploy a probe at runtime, such as generated class files and the .probescript file.

Probe sets must be unique within the registry. Probe sets are primarily identified by their id (see org.eclipse.hyades.models.probekit). If there is an entry in the registry for a given id, it is always replaced by any new entry with the same id. Probe sets which do not have an id will be assigned one by the registry.

In addition, if there is a source file associated with the probe set, the source file is also used in determining probe set equivalence. Two probe sets are equivalent if either their id or their source file names match. When making a new entry, any existing equivalent entries are supplanted by the new entry.

To add a probe set to the registry through an import file, use addIfNoConflict(), along with commit() and discard() for conflict resolution. To add a probe set without worrying about conflicts (e.g. blindly overwrite conflicting entries), use one of the add() methods.

Probes sets added to the registry through import files have their files managed by the registry. They're stored in the plugin's state save area. Probe sets added to the registry by the builder have their files managed by the workbench.

Consumers who want to use the import thru zip file interface should also refer to org.eclipse.tptp.platform.probekit.registry.CandidateEntry.

Nested Class Summary

protected class

ProbeRegistry.Enumerator This class encapsulates a read-only Enumeration/Iterator over the contents of the registry.

Field Summary

protected java.util.HashMap	srcMap Mapping from source name to registry entry.
protected java.util.Hashtable	store This represents all the probe sets the registry knows about.
protected static ProbeRegistry	theRegistry The registry singleton object.

Constructor Summary

protected

ProbeRegistry()

Method Summary

ProbeRegistryEntry	add(ProbeResourceBundle bundle) Add a probe set to the registry by supplying all the required pieces in a bundle.
ProbeRegistryEntry	add(java.lang.String importFileName) Add a probe set to the registry from a file previously created by an export operation.
CandidateEntry	addIfNoConflict(java.lang.String importFileName) Attempt to import a probe set into the registry.
void	commit(CandidateEntry candidate) Commit a candidate entry to the registry.
java.util.Enumeration	contents() Create an iterator over the registry contents.
void	discard(CandidateEntry candidate) Throw away a candidate entry.
static ProbeRegistry	getRegistry() Get a reference to the one and only registry.
java.util.Iterator	iterator() Create an iterator over the registry contents.
ProbeRegistryEntry	lookupById(java.lang.String id) Locate the entry corresponding to a particular id.
ProbeRegistryEntry	lookupBySource(org.eclipse.core.resources.IResource source) Retrieve a probe set based on its source (.probe) file reference.
protected void	purgeFreeList() Delete entries marked for deferred deletion.
void	remove(org.eclipse.core.resources.IResource source) Remove the entry corresponding to a particular .probe source file.
void	remove(ProbeRegistryEntry entry) Remove an entry from the probe registry.
void	remove(java.lang.String id) Remove the entry corresponding to a particular id from the registry.
void	restore(java.io.File saveFile) Restore previously saved registry state.
void	save(java.io.File saveFile) Save the registry state to persistent storage.
static void	startup() Perform registry startup tasks.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

theRegistry

protected static ProbeRegistry theRegistry

The registry singleton object. It is expected that there will only ever be one. If that ever changes, you'll need to reevaluate this whole class for thread safety.

store

protected java.util.Hashtable store

This represents all the probe sets the registry knows about. The probe set id's are the keys, ProbeRegistryEntry objects are the values. The registry store is based on HashTable, so it is synchronized.

srcMap

protected java.util.HashMap srcMap

Mapping from source name to registry entry. This is used to support operations like lookupBySource(), which in turn is needed so we can detect conflicting entries even when the id's change. Only authored probes are entered into the source map.

Constructor Detail

ProbeRegistry

protected ProbeRegistry()

Method Detail

getRegistry

public static ProbeRegistry getRegistry()

Get a reference to the one and only registry.

Returns:

The probe set registry.

startup

public static void startup()
                    throws ProbeRegistryException

Perform registry startup tasks. In particular, make sure we can get our hands on the storage area the registry uses for imported probe sets.

Throws:

ProbeRegistryException

save

public void save(java.io.File saveFile)
          throws ProbeRegistryException

Save the registry state to persistent storage. Use retore() to recover what is saved this way.

Parameters:

saveFile - The destination file for the registry state.

Throws:

ProbeRegistryException

restore

public void restore(java.io.File saveFile)
             throws ProbeRegistryException

Restore previously saved registry state. This should only be used to restore state information from a save() operation. The existing registry contents are completely replaced by the new state.

Parameters:

saveFile - A file created by the registry save() operation.

Throws:

ProbeRegistryException

add

public ProbeRegistryEntry add(java.lang.String importFileName)
                       throws java.io.IOException,
                              InvalidProbeBundleException

Add a probe set to the registry from a file previously created by an export operation. If a registry entry for this probe set is already present, it will be replaced by the contents of the new file.

Open the import file, extract the pieces to a probe registry managed location. Perform as much validation of the file contents as possible. Successful completion of this operation makes the probe set available for deployment.

Parameters:

importFileName - Reference to a file created by exporting a probe set.

Returns:

the newly created registry entry

Throws:

java.io.IOException - Unable to read or extract the import file contents

InvalidProbeBundleException - The import file is mal-formed. That is, it does not contain the expected files.

add

public ProbeRegistryEntry add(ProbeResourceBundle bundle)
                       throws ProbeRegistryException,
                              InvalidProbeBundleException

Add a probe set to the registry by supplying all the required pieces in a bundle. This is usually called by the ProbeBundler after a build. If a registry entry for this probe set is already present, it will be replaced by the contents of the bundle.

Parameters:

bundle - A complete probe resource bundle, including persisted model file, probescript, and one or more supporting class files.

Returns:

The newly created registry entry.

Throws:

ProbeRegistryException - The probe bundle is incomplete or otherwise badly formed.

InvalidProbeBundleException

remove

public void remove(ProbeRegistryEntry entry)

Remove an entry from the probe registry. If entry is not in the registry, this call does nothing. If entry is an imported probe set, its probescript & class files will also be removed from the registry managed on-disk storage.

Parameters:

entry - registry entry to remove

remove

public void remove(java.lang.String id)

Remove the entry corresponding to a particular id from the registry.

Parameters:

id - Probe set identifier of the entry to remove

remove

public void remove(org.eclipse.core.resources.IResource source)

Remove the entry corresponding to a particular .probe source file. If there there is no entry for this Resource, the request is ignored.

Parameters:

source - The probe source Resource of registry entry to be removed.

contents

public java.util.Enumeration contents()

Create an iterator over the registry contents. The order is not defined. The resulting enumerator is read-only and cannot be used to modify the registry contents. If the registry contents change during the lifetime of the enumerator, the changes will not be reflected in the enumerated set. This method is equivalent to the iterator() method, except that it returns an Enumeration instead of an Iterator.

Returns:

an enumeration that can be used to walk the registry contents.

iterator

public java.util.Iterator iterator()

Create an iterator over the registry contents. The order is not defined. The resulting iterator is read-only and cannot be used to modify the registry contents. If the registry contents change during the lifetime of the enumerator, the changes will not be reflected in the enumerated set. This method is equivalent to the contents() method, except that it returns an Iterator instead of an Enumeration.

Returns:

an iterator that can be used to walk the registry contents.

lookupById

public ProbeRegistryEntry lookupById(java.lang.String id)

Locate the entry corresponding to a particular id.

Parameters:

id - Probe set identifier of the entry to locate

Returns:

the matching entry, if found; null if not found.

lookupBySource

public ProbeRegistryEntry lookupBySource(org.eclipse.core.resources.IResource source)

Retrieve a probe set based on its source (.probe) file reference. This query is really only meaningful on authored probes in the workspace. Imported probes in the registry save area are not resources (and do not necessarily have source).

Parameters:

source - The probe set source file, as an IPath.

Returns:

The matching entry, or null if not found.

addIfNoConflict

public CandidateEntry addIfNoConflict(java.lang.String importFileName)
                               throws java.io.IOException,
                                      InvalidProbeBundleException

Attempt to import a probe set into the registry. A tentative or "candidate" registry entry is created and decorated with enough information to tell the caller whether or not there is a conflicting entry in the registry. If there is no conflict, the entry is automatically added to the registry. Otherwise, the caller should either commit this candidate entry to the registry or explicitly discard it.

A conflicting entry is any one with the same probe set id. It is up to the caller to decide whether or not to proceed with the import (and thereby overwrite the existing entry). See the commit() and discard() operations.

When there is a conflict, a lock is placed on the conflicting entry. The lock is released when the candidate is either committed or discarded. While the conflicting entry is locked, no other thread can successfully pre-flight a probe set with the same id or explicitly add() a conflicting entry. This ensures the state of the contentious probe set does not change between preflight() and commit()/discard().

Parameters:

importFileName - A previously exported probe set package

Returns:

A candidate registry entry that can be queried for conflict resolution.

Throws:

java.io.IOException - Unable to read/extract the import file

InvalidProbeBundleException - import file is badly formed. That is, it does not contain the expected files.

commit

public void commit(CandidateEntry candidate)
            throws ProbeRegistryException,
                   InvalidProbeBundleException

Commit a candidate entry to the registry. No conflict resolution is performed. That is, the conflicting entry (if any) is always overwritten. This operation is a no-op if there was no conflict to begin with because addIfNoConflict will already have committed the candidate.

Once this operation succeeded, candidate is invalid and should not be committed or discarded again.

Parameters:

candidate - A candidate registry entry, previously created by preflight()

Throws:

ProbeRegistryException - candidate was previously committed or discarded.

InvalidProbeBundleException

discard

public void discard(CandidateEntry candidate)
             throws ProbeRegistryException

Throw away a candidate entry. The registry will clean up any temporary files created by the preflight() operation and release all associated locks. If there is no conflict, addIfNoConflict() already added it to the registry and you cannot now meaningfully discard it, so an exception is thrown.

Once this operation has succeeded, the candidate entry is invalid and cannot committed or discarded again.

Parameters:

candidate - The candidate registry entry to discard.

Throws:

ProbeRegistryException - candidatewas previously committed or discarded.

purgeFreeList

protected void purgeFreeList()

Delete entries marked for deferred deletion.