Merge branch 'KnowledgeContainers' into ISOLA2016

jdeeco-core/src/cz/cuni/mff/d3s/deeco/ensembles/EnsembleFactory.java

@@ -0,0 +1,9 @@
+package cz.cuni.mff.d3s.deeco.ensembles;
+
+import java.util.Collection;
+
+import cz.cuni.mff.d3s.deeco.knowledge.container.KnowledgeContainer;
+
+public interface EnsembleFactory {
+	Collection<EnsembleInstance> createInstances(KnowledgeContainer container);
+}

jdeeco-core/src/cz/cuni/mff/d3s/deeco/ensembles/EnsembleInstance.java

@@ -0,0 +1,5 @@
+package cz.cuni.mff.d3s.deeco.ensembles;
+
+public interface EnsembleInstance {
+	void performKnowledgeExchange();
+}

jdeeco-core/src/cz/cuni/mff/d3s/deeco/ensembles/intelligent/package-info.java

@@ -0,0 +1,9 @@
+/**
+ * 
+ */
+/**
+ * @author Filip Krijt
+ * @author Zbyněk Jiráček
+ *
+ */
+package cz.cuni.mff.d3s.deeco.ensembles.intelligent;

jdeeco-core/src/cz/cuni/mff/d3s/deeco/ensembles/package-info.java

@@ -0,0 +1,9 @@
+/**
+ * 
+ */
+/**
+ * @author Filip Krijt
+ * @author Zbyněk Jiráček
+ *
+ */
+package cz.cuni.mff.d3s.deeco.ensembles;

jdeeco-core/src/cz/cuni/mff/d3s/deeco/knowledge/container/KnowledgeContainer.java

@@ -0,0 +1,69 @@
+package cz.cuni.mff.d3s.deeco.knowledge.container;
+
+import java.util.Collection;
+
+import cz.cuni.mff.d3s.deeco.annotations.PlaysRole;
+import cz.cuni.mff.d3s.deeco.annotations.Role;
+
+/**
+ * Knowledge container is useful when operating with multiple component's knowledge. It provides access to
+ * the knowledge via roles.
+ * 
+ * @author Zbyněk Jiráček
+ * 
+ * @see TrackingKnowledgeContainer
+ * @see Role
+ * @see PlaysRole
+ *
+ */
+public interface KnowledgeContainer {
+
+	/**
+	 * Traverses through all underlying knowledge and for each knowledge implementing the specified
+	 * role it returns an instance of the role class. This instance represents a view on the component's
+	 * knowledge.
+	 * @param roleClass The role class.
+	 * @return Instances of the role class for each component that implements the specified role.
+	 * @throws KnowledgeContainerException
+	 */
+	public abstract <TRole> Collection<TRole> getUntrackedKnowledgeForRole(
+			Class<TRole> roleClass) throws KnowledgeContainerException;
+
+	/**
+	 * Similarly to the {@link #getUntrackedKnowledgeForRole(Class)} it returns role view on the components'
+	 * knowledge. Additionally, the returned instances are tracked, which means that if the caller modifies
+	 * the returned instances and calls the {@link #commitChanges()} method, the changes will be propagated
+	 * into the component knowledge.
+	 * @param roleClass The role class.
+	 * @return Instances of the role class for each component that implements the specified role.
+	 * @throws KnowledgeContainerException
+	 *
+	 * @see #getUntrackedKnowledgeForRole(Class)
+	 * @see #commitChanges()
+	 * @see #resetTracking()
+	 */
+	public abstract <TRole> Collection<TRole> getTrackedKnowledgeForRole(
+			Class<TRole> roleClass) throws KnowledgeContainerException;
+
+	/**
+	 * Clears the list of tracked role class instances returned by the {@link #getTrackedKnowledgeForRole(Class)} method.
+	 * Consequently, changes to the earlier returned role class instances cannot be committed into the knowledge anymore.
+	 * 
+	 * @see #commitChanges()
+	 * @see #getTrackedKnowledgeForRole(Class)
+	 */
+	public abstract void resetTracking();
+
+	/**
+	 * Commits all the changes made to the tracked role class instances returned by the {@link #getTrackedKnowledgeForRole(Class)}
+	 * method (if the tracking was not reset by the {@link #resetTracking()} method). All values in the tracked role
+	 * class instances are stored into the respective knowledge.
+	 * 
+	 * @throws KnowledgeContainerException
+	 * 
+	 * @see #getTrackedKnowledgeForRole(Class)
+	 * @see #resetTracking()
+	 */
+	public abstract void commitChanges() throws KnowledgeContainerException;
+
+}

jdeeco-core/src/cz/cuni/mff/d3s/deeco/knowledge/container/TrackingKnowledgeContainer.java

@@ -9,16 +9,18 @@
 import cz.cuni.mff.d3s.deeco.knowledge.ReadOnlyKnowledgeManager;
 
 /**
- * Knowledge container is useful when operating with multiple component's knowledge (one local knowledge and multiple
- * shadow knowledge instances).
+ * An implementation of the {@link KnowledgeContainer} interface that is using knowledge managers.
  * 
- * A knowledge container creates a wrapper above all knowledge managers and allows for acquiring the knowledge of
- * the components in an object-oriented way using roles.
+ * The tracking knowledge container creates a wrapper above all knowledge managers (one local and multiple shadow)
+ * and allows for acquiring the knowledge of the components in an object-oriented way using roles.
  * 
  * @author Zbyněk Jiráček
+ * 
+ * @see KnowledgeContainer
+ * @see KnowledgeManager
  *
  */
-public class TrackingKnowledgeContainer {
+public class TrackingKnowledgeContainer implements KnowledgeContainer {
 
 	private final TrackingKnowledgeWrapper localKnowledgeContainer;
 	private final Collection<ReadOnlyKnowledgeWrapper> shadowKnowledgeContainers; 
@@ -46,14 +48,10 @@ private Collection<ReadOnlyKnowledgeWrapper> getAllKnowledgeWrappers() {
 		return result;
 	}
 
-	/**
-	 * Traverses through all underlying knowledge managers and for each knowledge implementing the specified
-	 * role it returns an instance of the role class. This instance represents a view on the component's
-	 * knowledge.
-	 * @param roleClass The role class.
-	 * @return Instances of the role class for each component that implements the specified role.
-	 * @throws KnowledgeContainerException
+	/* (non-Javadoc)
+	 * @see cz.cuni.mff.d3s.deeco.knowledge.container.KnowledgeContainer#getUntrackedKnowledgeForRole(java.lang.Class)
 	 */
+	@Override
 	public <TRole> Collection<TRole> getUntrackedKnowledgeForRole(Class<TRole> roleClass) throws KnowledgeContainerException {
 		try {
 			List<TRole> result = new ArrayList<>();
@@ -71,19 +69,10 @@ public <TRole> Collection<TRole> getUntrackedKnowledgeForRole(Class<TRole> roleC
 		}
 	}
 
-	/**
-	 * Similarly to the {@link #getUntrackedKnowledgeForRole(Class)} it returns role view on the components'
-	 * knowledge. Additionally, the returned instances are tracked, which means that if the caller modifies
-	 * the returned instances and calls the {@link #commitChanges()} method, the changes will be propagated
-	 * into the component knowledge manager.
-	 * @param roleClass The role class.
-	 * @return Instances of the role class for each component that implements the specified role.
-	 * @throws KnowledgeContainerException
-	 *
-	 * @see #getUntrackedKnowledgeForRole(Class)
-	 * @see #commitChanges()
-	 * @see #resetTracking()
+	/* (non-Javadoc)
+	 * @see cz.cuni.mff.d3s.deeco.knowledge.container.KnowledgeContainer#getTrackedKnowledgeForRole(java.lang.Class)
 	 */
+	@Override
 	public <TRole> Collection<TRole> getTrackedKnowledgeForRole(Class<TRole> roleClass) throws KnowledgeContainerException {
 		try {
 			List<TRole> result = new ArrayList<>();
@@ -107,31 +96,22 @@ public <TRole> Collection<TRole> getTrackedKnowledgeForRole(Class<TRole> roleCla
 		}
 	}
 
-	/**
-	 * Clears the list of tracked role class instances returned by the {@link #getTrackedKnowledgeForRole(Class)} method.
-	 * Consequently, changes to the earlier returned role class instances cannot be committed into the knowledge manager anymore.
-	 * 
-	 * @see #commitChanges()
-	 * @see #getTrackedKnowledgeForRole(Class)
+	/* (non-Javadoc)
+	 * @see cz.cuni.mff.d3s.deeco.knowledge.container.KnowledgeContainer#resetTracking()
 	 */
+	@Override
 	public void resetTracking() {
 		localKnowledgeContainer.resetTracking();
 		// shadow knowledge is read only
 	}
 
 	/**
-	 * Commits all the changes made to the tracked role class instances returned by the {@link #getTrackedKnowledgeForRole(Class)}
-	 * method (if the tracking was not reset by the {@link #resetTracking()} method). All values in the tracked role
-	 * class instances are stored into the respective knowledge managers.
-	 * 
+	 * @see cz.cuni.mff.d3s.deeco.knowledge.container.KnowledgeContainer#commitChanges()
+
 	 * PLEASE NOTE that currently, only data from the local knowledge manager can be updated. Shadow knowledge managers
 	 * are just read-only, therefore the changes to the shadow knowledge are discarded.
-	 * 
-	 * @throws KnowledgeContainerException
-	 * 
-	 * @see #getTrackedKnowledgeForRole(Class)
-	 * @see #resetTracking()
 	 */
+	@Override
 	public void commitChanges() throws KnowledgeContainerException {
 		try {
 			localKnowledgeContainer.commitChanges();

jdeeco-core/src/cz/cuni/mff/d3s/deeco/knowledge/container/package-info.java

@@ -10,7 +10,8 @@
  * {@link cz.cuni.mff.d3s.deeco.knowledge.container.ReadOnlyKnowledgeWrapper}.
  * 
  * When dealing with multiple components at once, knowledge container comes useful. A knowledge
- * container is an instance of the {@link cz.cuni.mff.d3s.deeco.knowledge.container.TrackingKnowledgeContainer}
+ * container is a subclass of the {@link cz.cuni.mff.d3s.deeco.knowledge.container.KnowledgeContainer}
+ * interface, namely the {@link cz.cuni.mff.d3s.deeco.knowledge.container.TrackingKnowledgeContainer}
  * class.
  * 
  * Knowledge wrappers and knowledge container use roles for accessing the knowledge. If a DEECo