plugin architecture enhancements and javadoc

jdeeco-core/src/cz/cuni/mff/d3s/deeco/annotations/processor/AnnotationProcessor.java

@@ -153,7 +153,7 @@ enum ParsingEvent {
 	 * Processors to handle additional annotations that are not handled by the main processor.
 	 * They are called via the <code>callExtensions()</code>. 
 	 */
-	AnnotationProcessorExtensionPoint[] extensions;
+	List<AnnotationProcessorExtensionPoint> extensions;
 
 	KnowledgeManagerFactory knowledgeManagerFactory;
 
@@ -176,11 +176,25 @@ public AnnotationProcessor(RuntimeMetadataFactory factory, RuntimeMetadata model
 			AnnotationProcessorExtensionPoint... extensions) {
 		this.factory = factory;
 		this.model = model;
-		this.extensions = extensions;
+		if (extensions.length == 0) {
+			this.extensions = new ArrayList<>();
+		} else {
+			this.extensions = Arrays.asList(extensions);
+		}
 		this.knowledgeManagerFactory = knowledgeMangerFactory;	
 		this.cloner = new Cloner();
 	}
 
+	/**
+	 * To be used to register an extension to the main annotation processor.
+	 * All registered extensions get notified at different stages in the parsing process.  
+	 * 
+	 * @see #callExtensions
+	 */
+	public void addExtension(AnnotationProcessorExtensionPoint extension) {
+		extensions.add(extension);
+	}
+
 	/**
 	 * Processing of one/multiple files provided as different parameters or as a single parameter-array of component objects 
 	 * 
@@ -1258,7 +1272,7 @@ String getComponentId(ChangeSet initialK) {
 	 * @param unknownAnnotations	annotations delegated to the callee
 	 */
 	private void callExtensions(ParsingEvent event, Object object, List<Annotation> unknownAnnotations) throws AnnotationProcessorException {
-		if ((extensions != null) && (extensions.length > 0)) {
+		if ((extensions != null) && (!extensions.isEmpty())) {
 			for (AnnotationProcessorExtensionPoint extension : extensions) {
 				Log.d("in 'CallExtensions': [EventType: "+ event + ", runtimeObject: " + object + ", extension: "+ extension +"]");
 				switch (event) {

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/DEECo.java

@@ -88,11 +88,21 @@ public <T extends DEECoPlugin> T getPluginInstance(Class<T> pluginClass) {
 	}
 
 	@Override
-	public RuntimeFramework getRuntime()
+	public RuntimeFramework getRuntimeFramework()
 	{
 		return runtime;
 	}
 
+	@Override
+	public AnnotationProcessor getProcessor() {
+		return processor;
+	}	
+
+	@Override
+	public RuntimeMetadata getRuntimeMetadata() {
+		return model;
+	}
+
 	class DependencyNode {
 		DEECoPlugin plugin; 
 		List<DependencyNode> dependantPlugins = new ArrayList<>();
@@ -129,7 +139,7 @@ List<DependencyNode> constructDependencyNodes(DEECoPlugin[] plugins) throws Plug
 		}
 
 		for (DependencyNode node: dependencyNodes) {
-			for (Class pluginClass : node.plugin.getDependencies()) {					
+			for (Class<? extends DEECoPlugin> pluginClass : node.plugin.getDependencies()) {					
 				if (knownPlugins.containsKey(pluginClass)) {
 					knownPlugins.get(pluginClass).dependantPlugins.add(node);						
 				} else {
@@ -176,5 +186,6 @@ private void createRuntime() {
 		scheduler.setExecutor(executor);
 		executor.setExecutionListener(scheduler);
 		runtime = new RuntimeFrameworkImpl(model, scheduler, executor, kmContainer);		
-	}	
+	}
+
 }

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/DEECoPlugin.java

@@ -2,9 +2,12 @@
 
 import java.util.List;
 
+import cz.cuni.mff.d3s.deeco.annotations.processor.AnnotationProcessorExtensionPoint;
+import cz.cuni.mff.d3s.deeco.annotations.processor.AnnotationProcessor;
+
 /**
  * Contains the specification of a DEECo plugin.
- * The core is itself a plugin, only it is always present. 
+ * The core is itself a plugin of type <code>RuntimeFramework</code>, only it is always present. 
  * Every plugin that has no explicit dependencies implicitly depends on the core plugin. 
  * 
  * @author Ilias Gerostathopoulos <iliasg@d3s.mff.cuni.cz>
@@ -14,14 +17,23 @@ public interface DEECoPlugin {
 
 	/**
 	 * The other plugins that this plugin depends on.
-	 * If its dependencies cannot be resolved, the plugin cannot be used.  
+	 * If its dependencies are not provided, the plugin will not be initialized and used.  
 	 */
-	@SuppressWarnings("rawtypes")
-	public List<Class> getDependencies();
+	public List<Class<? extends DEECoPlugin>> getDependencies();
 
 	/**
-	 * Registers all listeners for this plugin to different places in the plugins it depends on. 
-	 * @param container TODO
+	 * Method through which a plugin extends the plugins it depends on (or the DEECo core plugin, if it has no explicit dependencies).
+	 * <p>
+	 * It should be used to do one or more of the following:
+	 * <ul>
+	 * 	<li>Register an extension via {@link AnnotationProcessor#addExtension(AnnotationProcessorExtensionPoint)}.</li>
+	 *  <li>Register any other extension to different points of the runtime (similarly to the annotation processor)</li>
+	 *  <li>Deploy any "system" components or ensembles</li>
+	 *  <li>Connect the metadata model to its plugin-related extensions (other EMF models)</li>
+	 * </ul>
+	 * </p>
+	 *  
+	 * @param container main DEECo container that provides the necessary hooks to achieve the above extensions  
 	 */
 	public void init(DEECoPluginContainer container);	
 }

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/DEECoPluginContainer.java

@@ -1,10 +1,60 @@
 package cz.cuni.mff.d3s.deeco.runtime;
 
+import cz.cuni.mff.d3s.deeco.annotations.processor.AnnotationProcessor;
 import cz.cuni.mff.d3s.deeco.annotations.processor.AnnotationProcessorException;
+import cz.cuni.mff.d3s.deeco.model.runtime.api.RuntimeMetadata;
 
+/**
+ * Specifies the entry points of the main DEECo container available to DEECo plugins. 
+ * 
+ * @author Filip Krijt <krijt@d3s.mff.cuni.cz>
+ * @author Ilias Gerostathopoulos <iliasg@d3s.mff.cuni.cz>
+ */
 public interface DEECoPluginContainer {
-	public <T extends DEECoPlugin> T getPluginInstance(Class<T> clazz) ;	
-	public RuntimeFramework getRuntime();
+
+	/**
+	 * Returns the instance of the initialized plugin of type <code>pluginClass</code>.
+	 * To be called from the <code>init()</code> method of a plugin that depends on a plugin of type <code>pluginClass</code>.
+	 */
+	public <T extends DEECoPlugin> T getPluginInstance(Class<T> pluginClass) ;
+
+	/**
+	 * Returns the "core" plugin object (always present) of this DEECo container. 
+	 * Shorthand for <code>getPluginInstance(RuntimeFramework.class)</code>
+	 */
+	public RuntimeFramework getRuntimeFramework();
+
+	/**
+	 * Returns the annotations processor of this DEECo container.  
+	 * To be used by plugins that need to extend the annotation processor so that it can process new, plugin-related annotations.  
+	 */
+	public AnnotationProcessor getProcessor();
+
+	/**
+	 * Returns the runtime metadata model (EMF model) of this DEECo container.
+	 * To be used by plugins to connect the main EMF model with its plugin-related extensions.
+	 */
+	public RuntimeMetadata getRuntimeMetadata();
+
+	/**
+	 * Deploys components to the DEECo runtime by parsing them and adding them to the metadata model.
+	 * As soon as they are added to the model, components are dynamically deployed (relevant tasks are created and scheduled).
+	 * To be used by plugins to deploy "system components" that specify system processes to be scheduled along with application processes.
+	 * 
+	 * @param components initialized objects of component-annotated classes
+	 * @throws AnnotationProcessorException 
+	 */
 	public void deployComponents(Object... components) throws AnnotationProcessorException;
+
+	/**
+	 * Deploys ensembles to the DEECo rutime by parsing them and adding them to the metadata model.
+	 * As soon as they are added to the model, ensembles are dynamically deployed (relevant tasks are created and scheduled).
+	 * To be used by plugins to deploy "system ensembles" that specify knowledge exchange between "system components" and are scheduled along with application ensembles.
+	 * 
+	 * @param ensembles ensemble-annotated classes
+	 * @throws AnnotationProcessorException
+	 */
+	@SuppressWarnings("rawtypes")
 	public void deployEnsembles(Class... ensembles) throws AnnotationProcessorException;
+
 }

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/MissingDependencyException.java

@@ -8,7 +8,7 @@
 public class MissingDependencyException extends PluginDependencyException {	
 	private static final long serialVersionUID = 1L;
 
-	public MissingDependencyException(Class pluginWithMissingDependency, Class missingDependency) {
+	public MissingDependencyException(Class<? extends DEECoPlugin> pluginWithMissingDependency, Class<? extends DEECoPlugin> missingDependency) {
 		super("Missing dependency" + missingDependency + " for plugin "+ pluginWithMissingDependency + ".");
 	}
 }

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/RuntimeConfiguration.java

@@ -2,6 +2,8 @@
 
 
 /**
+ * @TODO(IG) : Check if it's OK to remove this class (the its tests) altogether
+ * 
  * A container for {@link RuntimeFramework} configuration options.
  * <p>
  * Hides the details of different options for runtime framework setup by providing a set of intuitive enums.

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/RuntimeFramework.java

@@ -5,6 +5,8 @@
 import cz.cuni.mff.d3s.deeco.scheduler.Scheduler;
 
 /**
+ * @TODO(IG) : Check if it's OK to remove this interface (the its tests) altogether
+ * 
  * JDEECo runtime framework management interface.
  * 
  * @author Jaroslav Keznikl <keznikl@d3s.mff.cuni.cz>

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/RuntimeFrameworkBuilder.java

@@ -14,6 +14,8 @@
 import cz.cuni.mff.d3s.deeco.scheduler.SingleThreadedScheduler;
 
 /**
+ * @TODO(IG) : Check if it's OK to remove this class (the its tests) altogether
+ * 
  * A builder for assembling a {@link RuntimeFramework} based on a
  * {@link RuntimeConfiguration}.
  * 

jdeeco-core/src/cz/cuni/mff/d3s/deeco/runtime/RuntimeFrameworkImpl.java

@@ -761,10 +761,9 @@ public RatingsManager getRatingsManager() {
 		return ratingsManager;
 	}
 
-	@SuppressWarnings("rawtypes")
 	@Override
-	public List<Class> getDependencies() {
+	public List<Class<? extends DEECoPlugin>> getDependencies() {
 		// this is the core plugin, so it has no dependencies and we return an empty list
-		return new ArrayList<Class>();
+		return new ArrayList<>();
 	}
 }