IProgressMonitor as a parameter in eclipse plugin programming

Question

I see a lot of eclipse plugin APIs that have IProgressMonitor as one of its parameters.

void setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor)
    throws JavaModelException;

1. What is this IProgressMonitor for? Do you have any good example?
2. Is it OK to pass null to it? Or do I have to create and pass an object (new ProgressMonitor())?

Answer 1

1) IProgressMonitor provides ways for the callee to report progress, rather than just status, to the caller. You can find examples in the article at http://www.eclipse.org/articles/Article-Concurrency/jobs-api.html , as well as its use throughout the Eclipse SDK.

2) null is only ever OK if the JavaDoc for that method says it is. Otherwise the assumption should be that it is not. The NullProgressMonitor implementation is of use in cases where null is forbidden but you still need to provide one.