[ADD] fixes and comments

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

@@ -8,8 +8,9 @@
 
 
 /**
- * Used to decorate a knowledge field with access restrictions 
- * 
+ * Used to decorate a knowledge field with access restrictions. The parameter
+ * is the security interface, i.e. interface decorated with {@link RoleDefinition} with possible parameters {@link RoleParam}. 
+ * This annotation can be used multiple times on the same field.
  * @author Ondřej Štumpf
  * 
  */
@@ -18,5 +19,5 @@
 @Target(ElementType.FIELD)
 @Repeatable(value=AllowMultiple.class)
 public @interface Allow {
-	Class<?> roleClass();
+	Class<?> value();
 }

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

@@ -7,7 +7,7 @@
 
 
 /**
- * Used to decorate a knowledge field with access restrictions 
+ * Container of {@link Allow} annotations, required by Java to enable repeatable annotations.
  * 
  * @author Ondřej Štumpf
  * 

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

@@ -8,7 +8,9 @@
 
 
 /**
- * Used to decorate a component with desired roles
+ * Used to decorate a component with desired roles. The parameter
+ * is the security interface, i.e. interface decorated with {@link RoleDefinition} with possible parameters {@link RoleParam}. 
+ * This annotation can be used multiple times on the same component.
  * 
  * @author Ondřej Štumpf
  * 
@@ -18,5 +20,5 @@
 @Target(ElementType.TYPE)
 @Repeatable(value=HasRoleMultiple.class)
 public @interface HasRole {
-	Class<?> roleClass();
+	Class<?> value();
 }

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

@@ -7,7 +7,7 @@
 
 
 /**
- * Used to decorate a component with desired roles
+ * Container of {@link HasRole} annotations, required by Java to enable repeatable annotations.
  * 
  * @author Ondřej Štumpf
  * 

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

@@ -5,8 +5,12 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import cz.cuni.mff.d3s.deeco.integrity.RatingsHolder;
+import cz.cuni.mff.d3s.deeco.integrity.ReadonlyRatingsHolder;
+
 /**
- * Marks a method parameter to contain a ranking for specified knowledge path.
+ * Used to decorate a rating process argument as a source of rating information.
+ * The only allowed types for such parameter are {@link RatingsHolder} and {@link ReadonlyRatingsHolder}.
  * 
  * @author Ondřej Štumpf
  * 

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

@@ -6,7 +6,7 @@
 import java.lang.annotation.Target;
 
 /**
- * Used to mark a method that performs an integrity check on component instance.
+ * Used to mark a method that performs an the rating in a component definition.
  * 
  * @author Ondřej Štumpf
  * 

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

@@ -7,7 +7,8 @@
 
 
 /**
- * Used to mark an interface as a security role
+ * Used to mark an interface as a security role. 
+ * Only such interfaces can be used as arguments for {@link Allow} and {@link HasRole} annotations.
  * 
  * @author Ondřej Štumpf
  * 

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

@@ -5,9 +5,17 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import cz.cuni.mff.d3s.deeco.model.runtime.api.AbsoluteSecurityRoleArgument;
+import cz.cuni.mff.d3s.deeco.model.runtime.api.BlankSecurityRoleArgument;
+
 
 /**
- * Used to mark a field within a role definition as a role parameter. Such field must be of type String, static and final.
+ * Used to mark a field within a security interface (interface decorated with {@link RoleDefinition} as a role parameter. 
+ * Such field must be static and final.
+ * The field can have following values:
+ *  - null, then {@link BlankSecurityRoleArgument} is created. This signals "any value is allowed".
+ *  - String in the format "[knowledge.path]" (including the brackets). The {@link PathSecurityRoleArgument}, which signals that the value of knowledge.path is used as a value of the parameter.
+ *  - any other object (including String not in the format above). Then {@link AbsoluteSecurityRoleArgument} with the object value is created.
  * 
  * @author Ondřej Štumpf
  * 

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

@@ -418,12 +418,12 @@ ComponentInstance createComponentInstance(Object obj) throws AnnotationProcessor
 
 			Set<Class<?>> roles = new HashSet<>();
 			for (HasRole role : clazz.getDeclaredAnnotationsByType(HasRole.class)) {
-				if (roles.contains(role.roleClass())) {
+				if (roles.contains(role.value())) {
 					throw new AnnotationProcessorException("The same role cannot be assigned multiply to a component.");
 				}
-				SecurityRole securityRole = createRoleFromClassDefinition(role.roleClass(), km, true);
+				SecurityRole securityRole = createRoleFromClassDefinition(role.value(), km, true);
 				componentInstance.getRoles().add(securityRole);
-				roles.add(role.roleClass());
+				roles.add(role.value());
 			}
 
 			callExtensions(ParsingEvent.ON_COMPONENT_CREATION, componentInstance, getUnknownAnnotations(clazz));
@@ -458,7 +458,7 @@ private cz.cuni.mff.d3s.deeco.model.runtime.api.RatingsProcess createRatingsProc
 	}
 
 	/**
-	 * Parses the class used as a role definition
+	 * Parses the class used as a role definition and returns the {@link SecurityRole} created from the class.
 	 * @param roleClass the class from annotation
 	 * @return
 	 * @throws AnnotationProcessorException
@@ -472,15 +472,18 @@ private SecurityRole createRoleFromClassDefinition(Class<?> roleClass, Knowledge
 		SecurityRole securityRole = factory.createSecurityRole();
 		securityRole.setRoleName(roleClass.getName());		
 
+		// create parent roles recursively
 		for (Class<?> iface : roleClass.getInterfaces()) {
 			securityRole.getConsistsOf().add(createRoleFromClassDefinition(iface, knowledgeManager, false));
 		}
 
+		// select only fields decorated with @RoleParam
 		List<Field> fieldParameters = Arrays.stream(roleClass.getFields())
 				.filter(field -> field.getAnnotationsByType(RoleParam.class).length > 0)				
 				.collect(Collectors.toList());
 
 		for (Field field : fieldParameters) {
+			// check if the field is not overriden by another field
 			if (!isValidForRole(field, fieldParameters, securityRole)) {
 				continue;
 			}			
@@ -495,9 +498,12 @@ private SecurityRole createRoleFromClassDefinition(Class<?> roleClass, Knowledge
 				throw new AnnotationProcessorException("Cannot read path from security role argument "+field.getName(), e);
 			}
 
+			// create appropriate argument from the field value
 			SecurityRoleArgument argument = createSecurityRoleArgument(field, fieldValue);						
 
 			securityRole.getArguments().add(argument);
+
+			// override argument values in parent roles
 			for (SecurityRole role : securityRole.getConsistsOf()) {
 				overrideArgument(argument, role);
 			}			
@@ -597,7 +603,7 @@ private void overrideArgument(SecurityRoleArgument argument, SecurityRole securi
 	}
 
 	/**
-	 * Checks whether the given field is an applicable argument for the role
+	 * Checks whether the given field is an applicable argument for the role (not being overriden).
 	 * @param field
 	 * @param fieldParameters
 	 * @param securityRole
@@ -639,14 +645,14 @@ private void addSecurityTags(Class<?> clazz, KnowledgeManager km, ChangeSet init
 			Set<Class<?>> roleClasses = new HashSet<>();
 
 			for (Allow allow : allows) {
-				if (roleClasses.contains(allow.roleClass())) {
-					throw new AnnotationProcessorException("Cannot assign the same role " + allow.roleClass().getSimpleName() + " multiple times.");
+				if (roleClasses.contains(allow.value())) {
+					throw new AnnotationProcessorException("Cannot assign the same role " + allow.value().getSimpleName() + " multiple times.");
 				}
 
 				KnowledgeSecurityTag tag = factory.createKnowledgeSecurityTag();
-				tag.setRequiredRole(createRoleFromClassDefinition(allow.roleClass(), km, true));
+				tag.setRequiredRole(createRoleFromClassDefinition(allow.value(), km, true));
 				km.addSecurityTag(kp, tag);			
-				roleClasses.add(allow.roleClass());				
+				roleClasses.add(allow.value());				
 			}
 
 		}		

jdeeco-core/src/cz/cuni/mff/d3s/deeco/integrity/PathRating.java

@@ -1,7 +1,10 @@
 package cz.cuni.mff.d3s.deeco.integrity;
 
+import cz.cuni.mff.d3s.deeco.annotations.RatingsProcess;
+
 /**
- * 
+ * Possible states of knowledge data. Components can use {@link RatingsProcess} and {@link RatingsHolder} to assign
+ * any of these values to a knowledge path.
  * @author Ondřej Štumpf
  *
  */

jdeeco-core/src/cz/cuni/mff/d3s/deeco/integrity/RatingsChangeSet.java

@@ -11,48 +11,78 @@
 import cz.cuni.mff.d3s.deeco.model.runtime.meta.RuntimeMetadataFactory;
 
 /**
- * 
+ * Represents a single change in the rating container.
  * @author Ondřej Štumpf
  *
  */
 public class RatingsChangeSet implements Serializable {
 
+	/** The Constant serialVersionUID. */
 	private static final long serialVersionUID = 2415324270333544655L;
 
-	private String authorComponentId, targetComponentId;
+	/** ID of the component that issued the rating. */
+	private String authorComponentId;
+
+	/** ID of the component whose knowledge is rated. */
+	private String targetComponentId;
+
+	/** The knowledge path that is rated. */
 	private KnowledgePath knowledgePath;
-	private PathRating rating;
 
+	/** The actual rating for the knowledge path. */
+	private PathRating rating;
+
 	public RatingsChangeSet(String authorComponentId, String targetComponentId, KnowledgePath knowledgePath, PathRating rating) {
 		this.authorComponentId = authorComponentId;
 		this.targetComponentId = targetComponentId;
 		this.knowledgePath = knowledgePath;
 		this.rating = rating;
 	}
 
+	/**
+	 * Gets the ID of the component that issued the rating.
+	 *
+	 * @return ID of the component
+	 */
 	public String getAuthorComponentId() {
 		return authorComponentId;
 	}
 
+
+	/**
+	 * Gets the target component id.
+	 *
+	 * @return the target component id
+	 */
 	public String getTargetComponentId() {
 		return targetComponentId;
 	}
 
+	/**
+	 * Gets the knowledge path that is rated.
+	 *
+	 * @return the knowledge path
+	 */
 	public KnowledgePath getKnowledgePath() {
 		return knowledgePath;
 	}
 
+	/**
+	 * Gets the actual rating for the knowledge path.
+	 *
+	 * @return the path rating
+	 */
 	public PathRating getPathRating() {
 		return rating;
 	}
-
+		
 	private void writeObject(ObjectOutputStream oos) throws IOException {		
 		oos.writeUTF(getAuthorComponentId());
 		oos.writeUTF(getTargetComponentId());
 		oos.writeUTF(getKnowledgePath().toString());
 		oos.writeObject(getPathRating());		
 	}
-
+		
 	private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException {		
 		RuntimeMetadataFactory factory = new RuntimeMetadataFactoryExt();
 		authorComponentId = ois.readUTF();
@@ -69,6 +99,9 @@ private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IO
 		knowledgePath = kp;		
 	}
 
+	/* (non-Javadoc)
+	 * @see java.lang.Object#equals(java.lang.Object)
+	 */
 	@Override
 	public boolean equals(Object obj) {
 		if (this == obj)
@@ -109,6 +142,9 @@ public boolean equals(Object obj) {
 		return true;
 	}
 
+	/* (non-Javadoc)
+	 * @see java.lang.Object#toString()
+	 */
 	@Override
 	public String toString() {
 		return String.format("RatingsChangeSet: author=%s, target=%s, knowledge path=%s, rating=%s", authorComponentId, targetComponentId, knowledgePath, rating);

jdeeco-core/src/cz/cuni/mff/d3s/deeco/integrity/RatingsHolder.java

@@ -2,18 +2,33 @@
 
 import java.util.Map;
 
-
+import cz.cuni.mff.d3s.deeco.annotations.Rating;
+import cz.cuni.mff.d3s.deeco.annotations.RatingsProcess;
+import cz.cuni.mff.d3s.deeco.model.runtime.api.KnowledgePath;
 
 /**
- * 
- * @author Ondřej Štumpf
+ * Contains rating information about a single {@link KnowledgePath} of a single component.
+ * This class is passed as an argument to the {@link RatingsProcess} for those arguments that are decorated with {@link Rating}
  *
+ * @author Ondřej Štumpf
  */
 public class RatingsHolder extends ReadonlyRatingsHolder {
 
 	private PathRating oldRating, newRating;	
 	private final String askingComponentId, targetComponentId;
 
+	/**
+	 * Instantiates a new ratings holder.
+	 *
+	 * @param askingComponentId
+	 *            the ID of the component that asked for this holder (and later becomes author of the rating)
+	 * @param targetComponentId
+	 *            the ID of the component whose knowledge is being rated
+	 * @param rating
+	 *            the old rating
+	 * @param ratings
+	 *            the aggregated ratings from other components
+	 */
 	protected RatingsHolder(String askingComponentId, String targetComponentId, PathRating rating, Map<PathRating, Long> ratings) {
 		super(ratings);
 		this.oldRating = rating;
@@ -22,6 +37,12 @@ protected RatingsHolder(String askingComponentId, String targetComponentId, Path
 		this.targetComponentId = targetComponentId;
 	}
 
+	/**
+	 * Sets the rating.
+	 *
+	 * @param rating
+	 *            the new rating
+	 */
 	public void setMyRating(PathRating rating) {
 		this.oldRating = this.newRating;
 		this.newRating = rating;
@@ -39,18 +60,38 @@ public void setMyRating(PathRating rating) {
 		}		
 	}
 
+	/**
+	 * Gets the rating.
+	 *
+	 * @return the rating
+	 */
 	public PathRating getMyRating() {
 		return newRating;
 	}
 
+	/**
+	 * Checks if is dirty (i.e. the new rating is different from the original).
+	 *
+	 * @return true, if is dirty
+	 */
 	public boolean isDirty() {
 		return oldRating != newRating;
 	}
 
+	/**
+	 * Gets the ID of the component that asked for this holder (and later becomes author of the rating).
+	 *
+	 * @return the ID of the component
+	 */
 	protected String getAskingComponentId() {
 		return askingComponentId;
 	}
 
+	/**
+	 * Gets the ID of the component whose knowledge is being rated
+	 *
+	 * @return the ID of the component
+	 */
 	protected String getTargetComponentId() {
 		return targetComponentId;
 	}