Merge pull request #43 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

@@ -31,31 +31,37 @@ private AccessEvents() {
 
 	/**
 	 * Base name for all access management cycle events
+	 * @since 0.4.0
 	 */
 	public static final String TOPIC = TOPIC_BASE + TOPIC_SEP + "AccessEvents"; //$NON-NLS-1$
 
 	/**
 	 * Name for all access management events
+	 * @since 0.4.0
 	 */
 	public static final String TOPIC_ALL = TOPIC + TOPIC_SEP + ALL_SUB_TOPICS;
 
 	/**
 	 * Sent when {@link LicensingCondition}(s) are extracted
+	 * @since 0.4.0
 	 */
 	public static final String CONDITIONS_EXTRACTED = TOPIC + TOPIC_SEP + "conditionsExtracted"; //$NON-NLS-1$
 
 	/**
 	 * Sent when {@link LicensingCondition}(s) are evaluated
+	 * @since 0.4.0
 	 */
 	public static final String CONDITIONS_EVALUATED = TOPIC + TOPIC_SEP + "conditionsEvaluated"; //$NON-NLS-1$
 
 	/**
 	 * Sent when {@link FeaturePermission}(s) are examined
+	 * @since 0.4.0
 	 */
 	public static final String PERMISSIONS_EXAMINED = TOPIC + TOPIC_SEP + "permissionsExamined"; //$NON-NLS-1$
 
 	/**
 	 * Sent when restrictions are executed
+	 * @since 0.4.0
 	 */
 	public static final String RESTRICTIONS_EXECUTED = TOPIC + TOPIC_SEP + "restrictionsExecuted"; //$NON-NLS-1$
 

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

@@ -21,6 +21,7 @@
 /**
  * The main entry point to the licensing.
  *
+ * @see org.eclipse.passage.lic.api
  * @since 0.4.0
  */
 public interface AccessManager {
@@ -42,19 +43,79 @@ public interface AccessManager {
 	 * @see #evaluateConditions
 	 * @see #examinePermissons
 	 * @see #executeRestrictions
+	 * @see org.eclipse.passage.lic.api
+	 * @since 0.4.0
 	 */
 	LicensingResult executeAccessRestrictions(LicensingConfiguration configuration);
 
+	/**
+	 * Implementation of the first phase of <i>access cycle</i>: <i>requirements resolution</i>.
+	 * Here {@link LicensingRequirement}s are retrieved from a running program physical artifacts.
+	 *
+	 * @param configuration general configuration for the whole <i>access cycle</i>
+	 * @return all the requirements resolved
+	 * @see LicensingRequirement
+	 * @see org.eclipse.passage.lic.api.requirements.RequirementResolver
+	 * @see org.eclipse.passage.lic.api
+	 * @since 0.4.0
+	 */
 	Iterable<LicensingRequirement> resolveRequirements(LicensingConfiguration configuration);
 
+	/**
+	 * Implementation of the second phase of <i>access cycle</i>: <i>condition mining</i>.
+	 * Here {@link LicensingCondition}s are gained from license information sources of sorts.
+	 *
+	 * @param configuration general configuration for the whole <i>access cycle</i>
+	 * @return all the conditions mined
+	 * @see LicensingCondition
+	 * @see org.eclipse.passage.lic.api.conditions.ConditionMiner
+	 * @see org.eclipse.passage.lic.api
+	 * @since 0.4.0
+	 */
 	Iterable<LicensingCondition> extractConditions(LicensingConfiguration configuration);
 
+
+	/**
+	 * Implementation of the third phase of <i>access cycle</i>: <i>condition evaluation</i>,
+	 * where a {@link LicensingCondition} is analysed on how it's terms are satisfied in the current program runtime.
+	 * In case the {@link LicensingCondition} is fully satisfied, a {@link FeaturePermission} is emitted.
+	 *
+	 * @param configuration general configuration for the whole <i>access cycle</i>
+	 * @param conditions    all the conditions to be evaluated
+	 * @return all the permissions granted
+	 * @see PermissionEmitter
+	 * @see org.eclipse.passage.lic.api
+	 * @since 0.4.0
+	 */
 	Iterable<FeaturePermission> evaluateConditions(LicensingConfiguration configuration,
 			Iterable<LicensingCondition> conditions);
 
+	/**
+	 * Implementation of the fourth phase of <i>access cycle</i>: <i>permission examining</i>.
+	 * Here {@link FeaturePermission}s are examined on how fully they satisfy
+	 * all the {@link LicensingRequirement}s.
+	 *
+	 * @param configuration general configuration for the whole <i>access cycle</i>
+	 * @param permissions   all the {@link FeaturePermission} emitted at the third phase of <i> access cycle</i>
+	 * @param requirements  all the {@link LicensingRequirement}s resolved at the first phase of <i> access cycle</i>
+	 * @return set of restriction verdicts for all the {@code requirements} that are not fully satisfied by the given {@code permissions}
+	 * @see RestrictionVerdict
+	 * @see org.eclipse.passage.lic.api.conditions.ConditionMiner
+	 * @see org.eclipse.passage.lic.api
+	 * @since 0.4.0
+	 */
 	Iterable<RestrictionVerdict> examinePermissons(LicensingConfiguration configuration,
 			Iterable<LicensingRequirement> requirements, Iterable<FeaturePermission> permissions);
 
+	/**
+	 * Implementation of the final phase of <i>restriction execution</i>: <i>permission examining</i>,
+	 * where all {@link RestrictionVerdict}s gained at the previous phase are applied to the program runtime.
+	 *
+	 * @param configuration general configuration for the whole <i>access cycle</i>
+	 * @param restrictions  restriction verdicts to be applied
+	 * @see org.eclipse.passage.lic.api
+	 * @since 0.4.0
+	 */
 	LicensingResult executeRestrictions(LicensingConfiguration configuration,
 			Iterable<RestrictionVerdict> restrictions);
 

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

@@ -32,23 +32,27 @@ public interface FeaturePermission {
 
 	LicensingConfiguration getLicensingConfiguration();
 
-    /**
-     * The original {@code LicensingCondition} for which this {@link FeaturePermission} was emitted.
-     */
+	/**
+	 * The original {@code LicensingCondition} for which this {@link FeaturePermission} was emitted.
+	 *
+	 * @since 0.4.0
+	 */
 	LicensingCondition getLicensingCondition();
 
-    /**
-     * In general case a {@link FeaturePermission} is time-limited.
-     * {@code LeaseDate} is timestamp of the permission emission.
-     *
-     * @see #getExpireDate()
-     */
+	/**
+	 * In general case a {@link FeaturePermission} is time-limited.
+	 * {@code LeaseDate} is timestamp of the permission emission.
+	 *
+	 * @see #getExpireDate()
+	 * @since 0.4.0
+	 */
 	Date getLeaseDate();
 
-    /**
-     * The date of the permission expiration. It is no longer valid after this date.
-     *
-     * @see #getLeaseDate()
-     */
+	/**
+	 * The date of the permission expiration. It is no longer valid after this date.
+	 *
+	 * @see #getLeaseDate()
+	 * @since 0.4.0
+	 */
 	Date getExpireDate();
 }

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

@@ -28,6 +28,7 @@ public interface LicensingRequest {
 	 * <code>"identifier"</code> attribute.
 	 *
 	 * @return the identifier
+	 * @since 0.5.0
 	 */
 	String getIdentifier();
 
@@ -36,6 +37,7 @@ public interface LicensingRequest {
 	 * <code>"creationDate"</code> attribute.
 	 *
 	 * @return the creation date
+	 * @since 0.5.0
 	 */
 	Date getCreationDate();
 
@@ -44,6 +46,7 @@ public interface LicensingRequest {
 	 * the value of its <code>"userIdentifier"</code> attribute.
 	 *
 	 * @return the user identifier
+	 * @since 0.5.0
 	 */
 	String getUserIdentifier();
 
@@ -52,6 +55,7 @@ public interface LicensingRequest {
 	 * the value of its <code>"userFullName"</code> attribute.
 	 *
 	 * @return the user full name
+	 * @since 0.5.0
 	 */
 	String getUserFullName();
 
@@ -60,6 +64,7 @@ public interface LicensingRequest {
 	 * is the value of its <code>"productIdentifier"</code> attribute.
 	 *
 	 * @return the product identifier
+	 * @since 0.5.0
 	 */
 	String getProductIdentifier();
 
@@ -68,6 +73,7 @@ public interface LicensingRequest {
 	 * This is the value of its <code>"productVersion"</code> attribute.
 	 *
 	 * @return the product version
+	 * @since 0.5.0
 	 */
 	String getProductVersion();
 
@@ -76,6 +82,7 @@ public interface LicensingRequest {
 	 * This is the value of its <code>"planIdentifier"</code> attribute.
 	 *
 	 * @return the plan identifier
+	 * @since 0.5.0
 	 */
 	String getPlanIdentifier();
 
@@ -85,6 +92,7 @@ public interface LicensingRequest {
 	 *
 	 * @return the valid from
 	 * @see LicensingCondition#getValidFrom()
+	 * @since 0.5.0
 	 */
 	Date getValidFrom();
 
@@ -94,6 +102,7 @@ public interface LicensingRequest {
 	 *
 	 * @return the valid until
 	 * @see LicensingCondition#getValidUntil()
+	 * @since 0.5.0
 	 */
 	Date getValidUntil();
 
@@ -103,6 +112,7 @@ public interface LicensingRequest {
 	 *
 	 * @return the condition type
 	 * @see LicensingCondition#getConditionType()
+	 * @since 0.5.0
 	 */
 	String getConditionType();
 
@@ -112,6 +122,7 @@ public interface LicensingRequest {
 	 *
 	 * @return the condition expression
 	 * @see LicensingCondition#getConditionExpression()
+	 * @since 0.5.0
 	 */
 	String getConditionExpression();
 

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

@@ -31,6 +31,7 @@ public interface PermissionEmitter {
 	 *
 	 * @param configuration general configuration for the whole <i>access cycle</i>
 	 * @param conditions source conditions to be evaluated against the current program runtime
+	 * @since 0.4.0
 	 */
 	Iterable<FeaturePermission> emitPermissions(LicensingConfiguration configuration,
 			Iterable<LicensingCondition> conditions) throws LicensingException;

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

@@ -19,16 +19,34 @@
  */
 public interface PermissionEmitterRegistry {
 
+	/**
+	 * @since 0.4.0
+	 */
 	String getDefaultConditionType();
 
+	/**
+	 * @since 0.4.0
+	 */
 	Iterable<String> getSupportedConditionTypes();
 
+	/**
+	 * @since 0.4.0
+	 */
 	String getConditionTypeName(String conditionType);
 
+	/**
+	 * @since 0.4.0
+	 */
 	String getConditionTypeDescription(String conditionType);
 
+	/**
+	 * @since 0.4.0
+	 */
 	PermissionEmitter getPermissionEmitter(String conditionType);
 
+	/**
+	 * @since 0.4.0
+	 */
 	Iterable<? extends PermissionEmitter> getPermissionEmitters();
 
 }

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

@@ -42,6 +42,7 @@ public interface PermissionExaminer {
 	 * @param permissions   feature permissions collected for the appropriate set of features
 	 * @return not null iterable structure of {@link RestrictionVerdict}s begotten by all the {@code requirements} unsatisfied
 	 * by the given {@code permissions}
+	 * @since 0.4.0
 	 */
 	Iterable<RestrictionVerdict> examine(LicensingConfiguration configuration,
 			Iterable<LicensingRequirement> requirements, Iterable<FeaturePermission> permissions);

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

@@ -24,14 +24,16 @@
 public interface PermissionTransport {
 
 	/**
-	 * Reads {@link FeaturePermission}s from the given {@link InputStream}. 
+	 * Reads {@link FeaturePermission}s from the given {@link InputStream}.
 	 *
+	 * @since 0.4.0
 	 */
 	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}.
 	 *
+	 * @since 0.4.0
 	 */
 	void writePermissions(Iterable<FeaturePermission> conditions, OutputStream output) throws IOException;