From 537de5e96bbdef06fc3e7c384af07b89fd3c6c16 Mon Sep 17 00:00:00 2001
From: "elena.parovyshnaya"
- * It represents the pair Runtime descriptor for the configuration being examined for restrictions. Represents the pair
- * Licensing exceptions contain a result object describing the cause of the
- * exception.
- * A checked exception representing a failure. Licensing exceptions contain a result object describing the cause of the exception.
- * AM serves the only purpose: a program under licensing, been run, can ask AM,
+ * {@link org.eclipse.passage.lic.api.access.AccessManager} serves the only purpose:
+ * a program under licensing, been run, can ask AM,
* if it is allowed to use a particular feature now,
* and the answer will be more or less simple yes or no.
* {id, version
} for the running product.
- * {id, version}
for the running product. create
+ *
+ * @since 0.4.0
*/
public static final String CREATE = "create"; //$NON-NLS-1$
+
/**
* Segment for events of type read
+ *
+ * @since 0.4.0
*/
public static final String READ = "read"; //$NON-NLS-1$
+
/**
* Segment for events of type update
+ *
+ * @since 0.4.0
*/
public static final String UPDATE = "update"; //$NON-NLS-1$
+
/**
* Segment for events of type delete
+ *
+ * @since 0.4.0
*/
public static final String DELETE = "delete"; //$NON-NLS-1$
/**
* Topic separator character
+ *
+ * @since 0.4.0
*/
public static final String TOPIC_SEP = "/"; //$NON-NLS-1$
@@ -50,11 +71,11 @@ public final class LicensingEvents {
/**
* Base name of all Licensing events
+ *
+ * @since 0.4.0
*/
public static final String TOPIC_BASE = "org/eclipse/passage/lic/api"; //$NON-NLS-1$
- private LicensingEvents() {
- // block
- }
+
}
diff --git a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingException.java b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingException.java
index df1c215d0..ad30e869f 100644
--- a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingException.java
+++ b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingException.java
@@ -13,14 +13,11 @@
package org.eclipse.passage.lic.api;
/**
- * A checked exception representing a failure.
- * 0x0
for a {@link #getSeverity severity}
* indicating the nominal case.
+ *
+ * @since 0.4.0
*/
int OK = 0x0;
/**
* The bit mask value 0x1
for a {@link #getSeverity severity}
* indicating the information.
+ *
+ * @since 0.4.0
*/
int INFO = 0x1;
/**
* The bit mask value 0x2
for a {@link #getSeverity severity}
* indicating the warning.
+ *
+ * @since 0.4.0
*/
int WARNING = 0x2;
/**
* The bit mask value 0x4
for a {@link #getSeverity severity}
* indicating the error.
+ *
+ * @since 0.4.0
*/
int ERROR = 0x4;
/**
* The bit mask value 0x8
for a {@link #getSeverity severity}
* indicating that the activity was canceled.
+ *
+ * @since 0.4.0
*/
int CANCEL = 0x8;
/**
* Returns an indicator of the severity of the problem.
+ *
+ * @since 0.4.0
*/
int getSeverity();
/**
* Returns a message describing the situation.
+ *
+ * @since 0.4.0
*/
String getMessage();
/**
* Returns the unique identifier of the source.
+ *
+ * @since 0.4.0
*/
String getSource();
/**
* Returns {@link #getSource source-specific} identity code.
+ *
+ * @since 0.4.0
*/
int getCode();
/**
* Returns the exception that caused this result, or null
if none.
+ *
+ * @since 0.4.0
*/
Throwable getException();
/**
* Returns the keys for the attached data.
+ *
+ * @since 0.4.0
*/
Iterablenull
if none
* @see #getAttachmentKeys()
+ *
+ * @since 0.4.0
*/
Object getAttachment(String key);
/**
* Returns the list of child {@link LicensingResult licensing results}.
+ *
+ * @since 0.4.0
*/
IterableAccess Management
* In a sentence
@@ -84,8 +91,8 @@ * registered properly at the program runtime, provides Requirements it is responsible for. * Each {@code Resolver} is designed to read a particular type of physical sources. * For example MANIFEST.MF, OSGi components manifest or other forms of annotations.
- * - * + *+ *
*
{@code Condition}s are mined from a license information of sorts, like license file or floating server. @@ -106,8 +113,8 @@ * Each {@code Miner} quarries {@code Condition}s from it's particular source according to it's own logic. * When AM collects @{code Condition}s, it queries all registered {@code Miner}s and aggregate all gained results. *
- * - * + *+ *
*
{@code Permission} are created by Passage at runtime as a result of a {@code Condition} evaluation. @@ -126,23 +133,41 @@ *
*
*
The process of examining must be implemented by an instance of {@link org.eclipse.passage.lic.api.access.PermissionExaminer}, + * registered in the system properly.
+ *{@code PermissionExaminer} takes the {@code requirements} in one hand and the {@code permissions} in the other one + * and carefully checks those {@code requirement}s one by one, if each one is satisfied by the given set of {@code permissions}.
+ *A fully satisfied {@code requirement} falls out of the further consideration. + * Thus, at the end of the day, all unsatisfied {@code requirement}s are found. + * For each of those a {@link org.eclipse.passage.lic.api.restrictions.RestrictionVerdict} is created.
+ *A {@code restriction} describes exhaustively the case of license insufficiency. + * Examining ends up with the set of such {@code restriction}s, empty in the perfect case.
+ *Roughly speaking, the examine says if the given {@code permissions} suffice to cover the given {@code requirements} or not.
**
*
There can be several instances of {@link org.eclipse.passage.lic.api.restrictions.RestrictionExecutor} interface.
+ *For a single {@code restriction} each registered {@code executor} is involved. + * There should be no meta-information analysis before asking an {@code executor} to do it's work. + * Some {@code executor}s can appear to be ok with a particular {@code restriction}, + * others (potentially several) can have something to do about it. + * Nevertheless, each registered {@code executor} will face each {@code restriction}.
+ *Such a behaviour is designed to prevent avoiding execution by registering a phony "i'm totally ok"-executor.
+ *{@code Executor} chose a behaviour according to the {@code restriction level} of the {@code restriction} under processing.
+ *