Merge pull request #42 from eparovyshnaya/547290

547290 Provide javadoc for org.eclipse.passage.lic.api.access package

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/AccessEvents.java

@@ -19,6 +19,8 @@
 import org.eclipse.passage.lic.api.conditions.LicensingCondition;
 
 /**
+ * Codes for Access Management cycle events.
+ *
  * @since 0.4.0
  */
 public final class AccessEvents {

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/AccessManager.java

@@ -19,24 +19,29 @@
 import org.eclipse.passage.lic.api.restrictions.RestrictionVerdict;
 
 /**
- * The main entry point to the licensing
+ * The main entry point to the licensing.
  *
  * @since 0.4.0
  */
 public interface AccessManager {
 
 	/**
-	 * Aggregated method to:
-	 * <li>resolve {@link LicensingRequirement}(s)</li>
-	 * <li>obtain {@link LicensingCondition}(s)</li>
-	 * <li>evaluate {@link LicensingCondition}(s) to emit
-	 * {@link FeaturePermission}(s)</li>
-	 * <li>examine requirements and permissions to compose
-	 * {@link RestrictionVerdict}(s)</li>
-	 * <li>execute {@link RestrictionVerdict}(s) to realize restrictions</li>
-	 * 
-	 * @param configuration
+	 * <p>Aggregating method for the full <i>access cycle</i>, which consists of the following steps:</p>
+	 * <ol><li>resolve {@link LicensingRequirement}s</li>
+	 *   <li>obtain {@link LicensingCondition}s</li>
+	 *   <li>evaluate {@link LicensingCondition}s to emit {@link FeaturePermission}s</li>
+	 *   <li>examine requirements and permissions to compose {@link RestrictionVerdict}s</li>
+	 *   <li>execute {@link RestrictionVerdict}s to realize restrictions</li>
+	 * </ol>
+	 *
+	 * @param configuration - general configuration for the licensing process
 	 * @return the composite result of execution
+	 * @see #resolveRequirements
+	 * @see #extractConditions
+	 * @see #evaluateConditions
+	 * @see #evaluateConditions
+	 * @see #examinePermissons
+	 * @see #executeRestrictions
 	 */
 	LicensingResult executeAccessRestrictions(LicensingConfiguration configuration);
 

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/PermissionEmitter.java

@@ -17,19 +17,20 @@
 import org.eclipse.passage.lic.api.conditions.LicensingCondition;
 
 /**
- * Interface of a service responsible for {@link LicensingCondition}s evaluation against the current program runtime.
- * As a result of evaluation, for a {@link LicensingCondition} a {@code FeaturePermission} can be emitted,
- * in case all the {@link LicensingCondition}'s terms are met at the current program runtime.
+ * Interface of a service responsible for the third step of <i> access cycle</i>: condition evaluation.
+ * According to the contract, a service must be able to evaluate given {@link LicensingCondition}s against the current program runtime.
+ * As a result of evaluation, for a {@link LicensingCondition} a {@link FeaturePermission} must be emitted
+ * in the case all of the {@link LicensingCondition}'s terms are met at the current program runtime.
  *
- * @see LicensingCondition
- * @see FeaturePermission
+ * @see org.eclipse.passage.lic.api.conditions.ConditionMiner
  * @since 0.4.0
  */
 public interface PermissionEmitter {
 	/**
-	 * Evaluates the collection of {@link LicensingCondition} to emit a collection
-	 * of {@link FeaturePermission}
+	 * Evaluates the collection of {@link LicensingCondition}s to emit a collection  of {@link FeaturePermission}.
 	 *
+	 * @param configuration general configuration for the whole <i>access cycle</i>
+	 * @param conditions source conditions to be evaluated against the current program runtime
 	 */
 	Iterable<FeaturePermission> emitPermissions(LicensingConfiguration configuration,
 			Iterable<LicensingCondition> conditions) throws LicensingException;

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/PermissionExaminer.java

@@ -18,7 +18,7 @@
 import org.eclipse.passage.lic.api.restrictions.RestrictionVerdict;
 
 /**
- * The contract for a service responsible for examining set of {@link FeaturePermission}s
+ * The contract for a service responsible for the forth phase of <i>access cycle</i>: examining set of {@link FeaturePermission}s
  * (runtime-evaluated {@code LicensingCondition}s)
  * against all {@link LicensingRequirement}s for the same set of features.
  * Examining reports which {@link LicensingRequirement}s are left unsatisfied.

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/access/PermissionTransport.java

@@ -17,20 +17,20 @@
 import java.io.OutputStream;
 
 /**
- * Transport interface for {@link FeaturePermission}(s)
+ * Transport interface for {@link FeaturePermission}s
  *
  * @since 0.4.0
  */
 public interface PermissionTransport {
 
 	/**
-	 * Reads {@link FeaturePermission}(s) from the given {@link InputStream}. 
+	 * Reads {@link FeaturePermission}s from the given {@link InputStream}. 
 	 *
 	 */
 	Iterable<FeaturePermission> readPermissions(InputStream input) throws IOException;
 
 	/**
-	 * Writes {@link FeaturePermission}(s) from the given {@link OutputStream}. 
+	 * Writes {@link FeaturePermission}s from the given {@link OutputStream}. 
 	 *
 	 */
 	void writePermissions(Iterable<FeaturePermission> conditions, OutputStream output) throws IOException;