org.netbeans.modules.j2ee.metadata.model.api

Class MetadataModel<T>

java.lang.Object

org.netbeans.modules.j2ee.metadata.model.api.MetadataModel<T>

public final class MetadataModel<T>
extends Object

Encapsulates a generic metadata model. The kind of metadata and the operation allowed on them is given by the T type parameter, and must be described to the client by the provider of the model.

Since:

1.2

Method Summary

Modifier and Type	Method and Description
boolean	isReady() Returns true if the metadata contained in the model correspond exactly to their source.
<R> R	runReadAction(MetadataModelAction<T,R> action) Executes an action in the context of this model and in the calling thread.
<R> Future<R>	runReadActionWhenReady(MetadataModelAction<T,R> action) Executes an action in the context of this model either immediately if the model is ready, or at a later point in time when the model becomes ready.

Methods inherited from class java.lang.Object

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

Method Detail

runReadAction

public <R> R runReadAction(MetadataModelAction<T,R> action)
                    throws MetadataModelException,
                           IOException

Executes an action in the context of this model and in the calling thread. This method is used to provide the model client with access to the metadata contained in the model.

This method provides safe access to the model in the presence of concurrency. It ensures that when the action's MetadataModelAction.run(T) method is running, no other thread can be running another action's run() method on the same MetadataModel instance. It also guarantees that the metadata does not change until the action's run() method returns.

This method does not, however, guarantee, that any piece of metadata obtained from the model as a result of invoking runReadAction() will still be present in the model when a subsequent invocation of runReadAction() takes place. As a result, clients are forbidden to call any methods on any piece of metadata obtained from the model outside the run() method of an action being executed as a result of an invocation of runReadAction(). In other words, pieces of metadata that are not explicitly documented as immutable are not allowed to escape the action's run() method.

This method may take a long time to execute. It is recommended that the method not be called from the AWT event thread. In some situations, though, the call needs to be made from the event thread, such as when computing the enabled state of an action. In this case it is recommended that the call not take place if the MetadataModel.isReady() method returns false (and a default value be returned as the result of the computation).

Parameters:

action - the action to be executed.

Returns:

the value returned by the action's run() method.

Throws:

MetadataModelException - if a checked exception was thrown by the action's run() method. That checked exception will be available as the return value of the getCause() method. This only applies to checked exceptions; unchecked exceptions are propagated from the run() method unwrapped.

IOException - if there was a problem reading the model from its storage (for example an exception occured while reading the disk files which constitute the source for the model's metadata).

NullPointerException - if the action parameter was null.

isReady

public boolean isReady()

Returns true if the metadata contained in the model correspond exactly to their source. For example, for a model containing metadata expressed in annotations in Java files, the model could be considered ready if no classpath scanning is taking place.

It is not guaranteed that if this method returns true, a subsequent invocation of runReadAction() will see the model in a ready state. Therefore this method is intended just as a hint useful in best-effort scenarios. For example the method might be used by a client which needs immediate access to the model to make its best effort to ensure that the model will at least not be accessed when not ready.

Returns:

true if the model is ready, false otherwise.

Since:

1.3

runReadActionWhenReady

public <R> Future<R> runReadActionWhenReady(MetadataModelAction<T,R> action)
                                     throws MetadataModelException,
                                            IOException

Executes an action in the context of this model either immediately if the model is ready, or at a later point in time when the model becomes ready. The action is executed in the calling thread if executed immediately, otherwise it is executed in another, unspecified thread.

The same guarantees with respect to concurrency and constraints with respect to re-readability of metadata that apply to runReadAction() apply to this method too. Furthermore, it is guaranteed that the action will see the model in a ready state, that is, when invoked by the action, the MetadataModel.isReady() method will return true.

This method may take a long time to execute (in the case the action is executed immediately). It is recommended that the method not be called from the AWT event thread.

Parameters:

action - the action to be executed.

Returns:

a Future encapsulating the result of the action's run() method. If the action was not run immediately and it threw an exception (checked or unchecked), the future's get() methods will throw an ExecutionException encapsulating that exception.

Throws:

MetadataModelException - if the action was run immediately and a checked exception was thrown by the action's run() method. That checked exception will be available as the return value of the getCause() method. This only applies to checked exceptions; unchecked exceptions are propagated from the run() method unwrapped.

IOException - if there was a problem reading the model from its storage (for example an exception occured while reading the disk files which constitute the source for the model's metadata).

NullPointerException - if the action parameter was null.

Since:

1.3