Revision as of 05:58, 7 January 2011

Work in progress

Features are grouped according to the interested actor :

• The end user uses existing discoverers through Eclipse workspace features
  
• The adopter uses existing discoverers through a dedicated Eclipse/Java API
  
• The adopter develop new discoverers through a dedicated Eclipse/Java API
  

Abstract

A general definition of MoDisco Discovery :

"A discovery is a process which takes an input source, and which aims to discover and return some information. This process may take in account some additional input data (discovery parameters) among which some are mandatory for the process."

End User Features

Creating a new Discoverer

To create a new MoDisco discoverer, you can use the wizard :

• File > New > Other...
• Select MoDisco > MoDisco Discoverer

You will be presented with a wizard that looks like this:

If you selected a project, source folder or Java package, then the first two fields are already filled in. If not, then click Browse... to select where you want to create your discoverer class.

• Class name : give a name to the new Java class for your discoverer
• Input type : select the Java type that your discoverer will take as input. For example, if your discoverer works on projects from the Eclipse workspace, then choose "org.eclipse.core.resources.IProject" from the dropdown list. If the type you want to use is not in the dropdown list, then you can either click the Browse... button and select it, or type it in.
• UI name : choose a user-friendly name for your discoverer, that will appear in the popup menu

Adopter Features

Discoverers declaration API

Developing a new Discoverer

Basics concepts

The framework proposes a Java interface org.eclipse.modisco.infra.discoverymanager.core.Discoverer<T> that every discoverer must implement.

 public interface Discoverer<T> {
    public boolean isApplicableTo(final T source);
    public IStatus discoverElement(final T source) throws DiscoveryException;
 }

• T : the java type for the source of the discovery
• isApplicableTo method: Determines if the source object can be handled by the discoverer. Each discoverer has to implement this method with its own criteria to filter the selected object. Such service will be used in some client generic behavior. e.g. for the end user, if the source object is managed by this discoverer, a discoverer menu will be available in the pop-up menu when users click with the contextual button.
• discoverElement method: Generic method for launching a discovery from a source element. The service might return some OK or CANCEL status, or throw some functional exception through DiscoveryException
• additional discovery parameters values (input or output) should be managed using fields and methods annotated with the org.eclipse.modisco.infra.discoverymanager.core.annotations.Parameter annotation.

Annotating your method/field as parameters of the discovery will enable generic description using the catalog API (see below) and so some client generic behavior (e.g. launchconfig feature for end user).

 @Target({ ElementType.METHOD, ElementType.FIELD })
 public @interface Parameter {
   public String name();
   public String description() default "";
   public boolean requiresInputValue() default false;
 }

The developer is free to annotate directly a Java field or a getter/setter method, or both field and getter/setter with a same id. See java documentation on org.eclipse.modisco.infra.discoverymanager.core.annotations.Parameter for details about the properties and the rules to comply with. Some compilation errors will appear if some of the rules are violated (project jdt apt processing must be turned on).

A small example

 public class BasicDiscoverer implements Discoverer<Object> {
 
   private String myParamIn;
   private URI myParamOut;
 
   @Parameter(name="PARAM_IN")
   public void setMyParamIn(String value) {
     this.myParamIn = value;
   }
 
   @Parameter(name="PARAM_OUT")
   public URI getMyParamOut() {
     return this.myParamOut;
   }
 
   public boolean isApplicableTo(Object source) {
     return ...;
   }
 
   public IStatus discoverElement(Object source) {
     ...
     return Status.OK_STATUS;
   }
 }

Note : inheritance is taken in account in the framework for generic description of a discoverer. i.e. Your discoverer class will inherit from the parameters declared (using annotation) on the super class or interfaces. The annotation validity rules will be checked against this whole parameters group.

The advanced API

Some usual parameters and behaviors have been grouped in abstract java discoverers for reuse.

org.eclipse.modisco.infra.discovery.core.AbstractDiscoverer proposes some usual services for testing the validity of the discovery source.

org.eclipse.modisco.infra.discovery.core.AbstractModelDiscoverer proposes some usual parameters for handling a model as result of the discovery (based on EMF org.eclipse.emf.ecore.Resource API). It also proposes some usual model creation and save actions.

Declaring a new Discoverer

A discoverer must declare a name and its Java implementation of the Discoverer interface to be managed by the Discoverers catalog (see below).

a org.eclipse.modisco.discoverers extension point allows to declare the discoverer, with the following fields :

• name - Required - information to identify a discoverer in the catalog; it must be unique. This name will also be used in some workspace end user features (e.g. launching popup menu)
• class - Required - A class that implements the Discoverer interface to be managed and used by the Discovery catalog.

Using the new Discoverer wizard

TODO documenter

Discoverers catalog and generic invocation API

The org.eclipse.modisco.infra.discoverymanager.core.DiscoveryCatalog class provides a registry of declared Discoverers in implementing this interface :

 public interface DiscoveryCatalog {
 
   public <T> DiscovererHandler<T> getDiscoverer(final String name);
   public Collection<DiscovererHandler<?>> getDiscoverers();
  
 }

The org.eclipse.modisco.infra.discoverymanager.core.DiscoveryHandler class provides some generic description and launching feature in implementing this interface

 public final interface DiscovererHandler<T> {
   public String getName();
   public Map<String, ParameterHandler> getParameterDefinitions();
   public IStatus discoverElement(final T source, final Map<String, Object> parametersValues) throws DiscoveryException;
 }

See java documentation associated to these classes for more details.