refactoring of kernel classes

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/IConnectionCompositor.java

@@ -19,13 +19,16 @@ package org.fortiss.tooling.kernel.extension;
 
 import org.eclipse.emf.ecore.EObject;
 import org.fortiss.tooling.kernel.extension.data.IConnectionCompositionContext;
+import org.fortiss.tooling.kernel.service.IConnectionCompositorService;
 import org.fortiss.tooling.kernel.service.base.IEObjectAware2;
 
 /**
- * Interface for connection compositors, i.e. classes which connect and
- * disconnect model elements. This may either be a direct connection or by using
- * an additional connection element.
- * 
+ * Interface for connection compositor extensions, i.e. classes which connect
+ * and disconnect model elements. This may either be a direct connection or by
+ * using an additional connection element.
+ * <P>
+ * Connection compositor extensions are handled by
+ * {@link IConnectionCompositorService}.
  * <P>
  * A typical example is the creation and removal of an edge in a graph editor.
  * The connection compositor links two nodes of the graph and aggregates the
@@ -41,14 +44,10 @@ import org.fortiss.tooling.kernel.service.base.IEObjectAware2;
  *            the meta-model class of target model elements handled by this
  *            compositor.
  * 
- * 
- *            TODO dead code? is this interface extended by anyone? what is the
- *            difference between this and "IConnectionCompositorService"
- * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: 1F11DAB103693D287729F0D68AD29A51
+ * @ConQAT.Rating YELLOW Hash: A461E86AAFAF15638C7557BDD5FFB68B
  */
 public interface IConnectionCompositor<P extends EObject, S extends EObject, T extends EObject>
 		extends IEObjectAware2<S, T> {

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/IConstraintChecker.java

@@ -19,10 +19,14 @@ package org.fortiss.tooling.kernel.extension;
 
 import org.eclipse.emf.ecore.EObject;
 import org.fortiss.tooling.kernel.extension.data.IConstraintViolation;
+import org.fortiss.tooling.kernel.service.IConstraintCheckerService;
 import org.fortiss.tooling.kernel.service.base.IEObjectAware;
 
 /**
  * Interface for constraint checker implementations.
+ * <P>
+ * Constraint checker extensions are handled by
+ * {@link IConstraintCheckerService}.
  * 
  * 
  * @param <C>
@@ -32,7 +36,7 @@ import org.fortiss.tooling.kernel.service.base.IEObjectAware;
  * @author hoelzlf
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: CA56F2FC176D99BE7804315FE3DBA6DD
+ * @ConQAT.Rating YELLOW Hash: E2CC5EF1073822B0237FAB3E5F609D51
  */
 public interface IConstraintChecker<C extends EObject> extends IEObjectAware<C> {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/IEclipseResourceStorageLocationProvider.java

@@ -18,22 +18,25 @@ $Id$
 package org.fortiss.tooling.kernel.extension;
 
 import org.eclipse.core.resources.IFile;
-import org.fortiss.tooling.kernel.internal.storage.eclipse.EclipseResourceStorageProvider;
+import org.fortiss.tooling.kernel.service.IEclipseResourceStorageService;
 
 /**
- * Extension interface for the {@link EclipseResourceStorageProvider} mechanism.
+ * Interface for providing Eclipse workspace resources as model files to the
+ * kernel. This interface is usually implemented by a class of the final tool
+ * product, e.g. the AF3 tool product uses <I>*.af3</I> as its model files.
+ * <P>
+ * Extensions are handled by the {@link IEclipseResourceStorageService}.
+ * <P>
  * The persistency storage provider, which uses Eclipse resources, does not know
  * which files should be considered model files. Therefore, a concrete product
  * built above the kernel is required to decide whether the file provided with
  * {@link #isStorageLocation(IFile)} should be considered.
  * 
- * @TODO: who implements this interface? (I could not find any class - is this a
- *        dead code?)
  * 
  * @author hoelzlf
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 21EF3B37635B8DDA74E646259CD52166
+ * @ConQAT.Rating YELLOW Hash: 6036762A8AD9A6300F2E9B1309662D02
  */
 public interface IEclipseResourceStorageLocationProvider {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/IElementCompositor.java

@@ -20,25 +20,26 @@ package org.fortiss.tooling.kernel.extension;
 import org.eclipse.emf.ecore.EObject;
 import org.fortiss.tooling.kernel.extension.data.IElementCompositionContext;
 import org.fortiss.tooling.kernel.extension.data.Prototype;
+import org.fortiss.tooling.kernel.service.IElementCompositorService;
 import org.fortiss.tooling.kernel.service.base.IEObjectAware;
 
 /**
- * Interface for compositors, i.e. classes which know how to compose and
- * decompose {@link EObject}s.
- * 
+ * Interface for element compositor extensions, i.e. classes which know how to
+ * compose and decompose {@link EObject}s.
+ * <P>
+ * Element compositor extensions are handled by
+ * {@link IElementCompositorService}.
  * <P>
  * A typical example is the adding and removal of a node in a graph editor. The
  * compositor adds the node to the graph as a child element.
  * 
- * TODO what is the difference between this an the IElementCompositorService?
- * 
  * @param <C>
  *            the meta-model class of the container element handled by this
  *            compositor.
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: 55AAA8CFC923138D7FC62924B1FD5208
+ * @ConQAT.Rating YELLOW Hash: 4793D9DD3334268CB2CAC0A959A56FF1
  */
 public interface IElementCompositor<C extends EObject> extends IEObjectAware<C> {
 	/**

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/IPrototypeProvider.java

@@ -21,9 +21,13 @@ import java.util.List;
 
 import org.eclipse.emf.ecore.EObject;
 import org.fortiss.tooling.kernel.extension.data.Prototype;
+import org.fortiss.tooling.kernel.service.IPrototypeService;
 
 /**
- * An {@link IPrototypeProvider} offers pre-configured {@link EObject}s.
+ * An {@link IPrototypeProvider} extension offers pre-configured {@link EObject}
+ * s.
+ * <P>
+ * Prototype provider extensions are handled by {@link IPrototypeService}.
  * 
  * A typical exmaple of a prototype is a model element, which also carries some
  * initial default layout information.
@@ -31,7 +35,7 @@ import org.fortiss.tooling.kernel.extension.data.Prototype;
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: B9EFDFBB6757268CE263BDB325ADF72B
+ * @ConQAT.Rating YELLOW Hash: 02459651984F56CAF5055BE52B0E1642
  */
 public interface IPrototypeProvider {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/IStorageProvider.java

@@ -21,23 +21,30 @@ import java.util.List;
 
 import org.fortiss.tooling.kernel.extension.data.ITopLevelElement;
 
-
 /**
  * An {@link IStorageProvider} implements a storage mechanism for EMF models. A
- * storage provider must deliver an {@link ITopLevelElement} for each
- * model under his supervision. It may rely on other parts of the Eclipse
- * workbench like the Team feature or EMFStore providing remote storage
- * capability. After the context was provided to the kernel it invokes the
- * methods of the context to execute commands, save, an so on.
+ * storage provider must deliver an {@link ITopLevelElement} for each model
+ * under his supervision. It may rely on other parts of the Eclipse workbench
+ * like the Team feature or EMFStore providing remote storage capability. After
+ * the context was provided to the kernel it invokes the methods of the context
+ * to execute commands, save, an so on.
+ * 
+ * <P>
+ * By default, the kernel uses the Eclipse workspace resources and XML-based
+ * file storage. See {@link IEclipseResourceStorageLocationProvider} for this
+ * persistency solution.
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: E87A345ADBF36DD5D10D19765D45CB31
+ * @ConQAT.Rating YELLOW Hash: 7DCBFE0BF5C4F3001EB6612D707B3E28
  */
 public interface IStorageProvider {
 
-	/** Returns the top-level elements provided by this storage provider. */
+	/**
+	 * Returns the top-level elements provided by this storage provider. This
+	 * method is called by persistency service during initialization. Only
+	 * successfully loaded models must be returned to the persitency service.
+	 */
 	List<ITopLevelElement> getTopLevelElementContexts();
-
 }

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/base/PrototypeProviderBase.java

@@ -37,7 +37,7 @@ import org.fortiss.tooling.kernel.extension.data.Prototype;
  * @author hoelzlf
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 8D5C4798D30B81D34FA49DDCCB466B04
+ * @ConQAT.Rating YELLOW Hash: 9E3EB670536CB826308AE303244A9D33
  */
 public abstract class PrototypeProviderBase implements IPrototypeProvider {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/base/package.html

+<!--  
+  $Id$
+  @version $Rev$
+  @ConQAT.Rating YELLOW Hash: BFA3AA34142126C434C02403B80670B9
+-->
+<body>
+Base implementations for extension classes of kernel extension points.
+</body>

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/data/IConnectionCompositionContext.java

@@ -28,15 +28,13 @@ import org.fortiss.tooling.kernel.extension.IConnectionCompositor;
  * obtained from the user's mouse drag gesture in some graphical editor, which
  * should be used when computing the composed connection's layout information.
  * 
- * TODO: we use quite extensively marker interfaces. What is their purpose? -
- * are they only for architecture documentation, or something else?
- * 
- * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 2D904303FDBDC14572DBE392859603DA
+ * @ConQAT.Rating YELLOW Hash: FBC55EDBE8003E3781A5D6C79B062FE1
  */
 public interface IConnectionCompositionContext {
 	// this is just a marker interface
+	// semantics of the context information is the concern of higher tool
+	// architecture layers
 }

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/data/IElementCompositionContext.java

@@ -31,8 +31,10 @@ import org.fortiss.tooling.kernel.extension.IElementCompositor;
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: 23C121BA36B5BBC85B457B0195BB5647
+ * @ConQAT.Rating YELLOW Hash: 481ACAA6E32399E69BEF87A33A670BDE
  */
 public interface IElementCompositionContext {
 	// this is just a marker interface
+	// semantics of the context information is the concern of higher tool
+	// architecture layers
 }

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/data/ITopLevelElement.java

@@ -31,15 +31,19 @@ import org.fortiss.tooling.kernel.extension.IStorageProvider;
  * running commands, listening to the command stack, undo and redo, a dirty
  * state and a save mechanism.
  * 
+ * <P>
+ * Once an instance of this interface is provided to the kernel, the underlying
+ * load must be completed successfully. Failure during the model loading must be
+ * handled by the storage provider. The kernel must only become aware of loaded
+ * models.
+ * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: DBEB1B9EEF064F64EA76CFFCAB2E8C39
+ * @ConQAT.Rating YELLOW Hash: 46D4B0852566538FAED1AB6B39AD22D9
  */
 public interface ITopLevelElement {
 
-	// @TODO: shouldn't we use a ProgressMonitor as well? (like saving, loading
-	// can be potentially slow)
 	/** Returns the top-level model element represented by this context. */
 	EObject getTopLevelElement();
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/data/Prototype.java

@@ -24,10 +24,10 @@ import org.eclipse.emf.ecore.util.EcoreUtil;
  * Prototypes consist of a generic description and pre-configured
  * {@link EObject}.
  * 
- * @author hoelzlf
+ * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating RED Hash:
+ * @ConQAT.Rating YELLOW Hash: 1D8DA4B2312BAB5112C0FDEA9EADB8E0
  */
 public final class Prototype {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/data/package.html

 <!--  
   $Id$
   @version $Rev$
-  @ConQAT.Rating YELLOW Hash: AAF3691F11B6715D160504127BDBA2DA
+  @ConQAT.Rating YELLOW Hash: 8559DA9A8CB872E4F00B04DAD51E8E17
 -->
 <body>
 Interfaces and classes for data transfer between the kernel and extensions.
 <P>
 The classes and interfaces of this package appear as parameter and result types of the
 interfaces in the <code>kernel.extension</code> package. Parameter objects resemble
-additional data provided to the extension, while result objects are required from the
-extension. Some of the result objects provide additional methods, which are used by the
+additional context data provided to the extension, while result objects are required from the
+extension.
+<P>
+On the kernel level the context information is usually empty, i.e., the respective interface
+is only a marker interface. Higher layers of the tool architecture may extend these interfaces
+with additional pieces of information. Here, the kernel is only the mediator between plugable
+parts of the tool.
+<P>
+Some of the result objects provide additional methods, which are used by the
 kernel at a later time after requesting it from the extension (e.g. once the
 <code>ITopLevelElement</code> is known to the kernel, the <code>runAsCommand</code>
 method will be called whenever some change to the model must be applied).

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/package.html

 <!--  
   $Id$
   @version $Rev$
-  @ConQAT.Rating YELLOW Hash: AAF3691F11B6715D160504127BDBA2DA
+  @ConQAT.Rating YELLOW Hash: DC71F316A934392F97E1B69B74FBC82E
 -->
 <body>
 Interface definitions for extension classes of kernel extension points.
 <P>
-Each interface corresponds to one extendable service from the <code>kernel.services</code> package
+Each interface corresponds to one extendable service from the <code>kernel.service</code> package
 and therefore to one extension point schema definition.
 <P>
 A plugable extension must implement the methods of the respective interface in order to work
 properly with the kernel implementation. These methods are called by the kernel at the appropriate time,
 e.g., a <code>IPrototypeProvider</code> is required to provide its prototype elements when the kernel
 calls the <code>getPrototypes()</code> method.
-
 <P>
 The communication between the kernel and extensions usually involves some kind of
-data (e.g. <code>Prototyp</code>). These data-related classes and interfaces can be
+data (e.g. <code>Prototype</code>). These data-related classes and interfaces can be
 found in the <code>kernel.extension.data</code> package.
+<P>
+For some extensions the kernel provides abstract base implementations in the
+<code>kernel.extension.base</code> package.
 </body>

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/internal/ConstraintService.java → org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/internal/ConstraintCheckerService.java

@@ -24,20 +24,20 @@ import java.util.List;
 import org.eclipse.emf.ecore.EObject;
 import org.fortiss.tooling.kernel.extension.IConstraintChecker;
 import org.fortiss.tooling.kernel.extension.data.IConstraintViolation;
-import org.fortiss.tooling.kernel.service.IConstraintService;
+import org.fortiss.tooling.kernel.service.IConstraintCheckerService;
 import org.fortiss.tooling.kernel.service.base.EObjectAwareServiceBase;
 
 /**
- * This class implements the {@link IConstraintService} interface.
+ * This class implements the {@link IConstraintCheckerService} interface.
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
  * @ConQAT.Rating GREEN Hash: B81C51C19484814E4EB0693AE12282DD
  */
-public class ConstraintService extends
+public class ConstraintCheckerService extends
 		EObjectAwareServiceBase<IConstraintChecker<EObject>> implements
-		IConstraintService {
+		IConstraintCheckerService {
 
 	/** The compositor extension point ID. */
 	private static final String EXTENSION_POINT_NAME = "org.fortiss.tooling.kernel.modelElementConstraintChecker";

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/internal/PersistencyService.java

@@ -174,8 +174,7 @@ public class PersistencyService implements IPersistencyService {
 	}
 
 	/** Notifies listener about top-level element removal. */
-	private synchronized void notifyListenersAboutRemove(
-			ITopLevelElement top) {
+	private synchronized void notifyListenersAboutRemove(ITopLevelElement top) {
 		for (IPersistencyServiceListener listener : listeners) {
 			listener.topLevelElementRemoved(top);
 		}

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/service/IConnectionCompositorService.java

@@ -18,6 +18,7 @@ $Id$
 package org.fortiss.tooling.kernel.service;
 
 import org.eclipse.emf.ecore.EObject;
+import org.fortiss.tooling.kernel.extension.IConnectionCompositor;
 import org.fortiss.tooling.kernel.extension.data.IConnectionCompositionContext;
 import org.fortiss.tooling.kernel.internal.ConnectionCompositorService;
 
@@ -29,15 +30,12 @@ import org.fortiss.tooling.kernel.internal.ConnectionCompositorService;
  * aggregated with some parent object and referencing two other objects in the
  * model element tree.
  * 
- * <P>
- * A typical example is the creation and removal of an edge in a graph editor.
- * The connection compositor links two nodes of the graph and aggregates the
- * edge with the graph as its parent element.
+ * @see IConnectionCompositor
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: EBFA052BA702812ED4FD5C17ED8F709B
+ * @ConQAT.Rating YELLOW Hash: A7FE0CEF3CF25444AE5F8E77B8F499EA
  */
 public interface IConnectionCompositorService {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/service/IConstraintService.java → org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/service/IConstraintCheckerService.java

@@ -22,21 +22,23 @@ import java.util.List;
 import org.eclipse.emf.ecore.EObject;
 import org.fortiss.tooling.kernel.extension.IConstraintChecker;
 import org.fortiss.tooling.kernel.extension.data.IConstraintViolation;
-import org.fortiss.tooling.kernel.internal.ConstraintService;
+import org.fortiss.tooling.kernel.internal.ConstraintCheckerService;
 
 /**
  * The constraint service manages registration and execution of model element
  * constraints.
  * 
+ * @see IConstraintChecker
+ * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: B16FC96E9123A6C4CD662DEF093AA954
+ * @ConQAT.Rating YELLOW Hash: 1933327D684530D680C0EFD712B4A39B
  */
-public interface IConstraintService {
+public interface IConstraintCheckerService {
 
 	/** Returns the singleton instance of the service. */
-	public static final IConstraintService INSTANCE = new ConstraintService();
+	public static final IConstraintCheckerService INSTANCE = new ConstraintCheckerService();
 
 	/**
 	 * Performs all constraint checks on the given model element and recursively

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/service/IEclipseResourceStorageService.java

@@ -26,10 +26,12 @@ import org.fortiss.tooling.kernel.extension.IEclipseResourceStorageLocationProvi
  * The eclipse storage service manages model files residing in the Eclipse
  * workspace as IFile resources.
  * 
+ * @see IEclipseResourceStorageLocationProvider
+ * 
  * @author hoelzlf
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating RED Hash:
+ * @ConQAT.Rating YELLOW Hash: BFC64E77516E911A8C868F964F7EB6CF
  */
 public interface IEclipseResourceStorageService {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/service/IElementCompositorService.java

@@ -30,14 +30,12 @@ import org.fortiss.tooling.kernel.internal.ElementCompositorService;
  * corresponds to an aggregation between the respective classes of the
  * meta-model.
  * 
- * <P>
- * A typical example is the adding and removal of a node in a graph editor. The
- * compositor adds the node to the graph as a child element.
+ * @see IElementCompositor
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: C7ED8EC9FDC7763BF3755FBEA4DEDE64
+ * @ConQAT.Rating YELLOW Hash: 28767D3487AB11E0BB918174285CA661
  */
 public interface IElementCompositorService {