From 537de5e96bbdef06fc3e7c384af07b89fd3c6c16 Mon Sep 17 00:00:00 2001 From: "elena.parovyshnaya" Date: Fri, 8 Nov 2019 12:40:50 +0300 Subject: [PATCH 1/2] 547289 - Provide javadoc for org.eclipse.passage.lic.api package -- put common lic.api classes' doc in order Signed-off-by: Elena Parovyshnaia --- .../lic/api/LicensingConfiguration.java | 17 +++++++++--- .../passage/lic/api/LicensingEvents.java | 27 ++++++++++++++++--- .../passage/lic/api/LicensingException.java | 15 ++++++----- .../passage/lic/api/LicensingReporter.java | 3 +++ .../passage/lic/api/LicensingResult.java | 26 ++++++++++++++++++ 5 files changed, 75 insertions(+), 13 deletions(-) diff --git a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingConfiguration.java b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingConfiguration.java index 4eb68f156..04bc483f3 100644 --- a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingConfiguration.java +++ b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingConfiguration.java @@ -13,17 +13,26 @@ package org.eclipse.passage.lic.api; /** - * Runtime descriptor for the configuration being examined for restrictions. - *

- * It represents the pair {id, version} for the running product. - *

+ *

Runtime descriptor for the configuration being examined for restrictions.

+ * + *

Represents the pair {id, version} for the running product.

* * @since 0.4.0 */ public interface LicensingConfiguration { + /** + * Id of the running product + * + * @since 0.4.0 + */ String getProductIdentifier(); + /** + * Precise version of the running product + * + * @since 0.4.0 + */ String getProductVersion(); } diff --git a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingEvents.java b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingEvents.java index 7ca6360b9..6d78d1a1c 100644 --- a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingEvents.java +++ b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingEvents.java @@ -13,6 +13,9 @@ package org.eclipse.passage.lic.api; /** + * + * Codes of licensing events + * * @since 0.4.0 */ public final class LicensingEvents { @@ -21,25 +24,43 @@ public final class LicensingEvents { public static final String PROPERTY_SOURCE = "org.eclipse.passage.lic.api.event.source"; //$NON-NLS-1$ public static final String PROPERTY_DATA = "org.eclipse.passage.lic.api.event.data"; //$NON-NLS-1$ public static final String PROPERTY_MESSAGE = "org.eclipse.passage.lic.api.event.message"; //$NON-NLS-1$ + + private LicensingEvents() { + // block + } + /** * Segment for events of type 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. - *

- * 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.

* - * @since 0.4.0 * @see LicensingResult + * @since 0.4.0 */ public class LicensingException extends Exception { @@ -28,11 +25,17 @@ public class LicensingException extends Exception { private LicensingResult diagnostic; + /** + * @since 0.4.0 + */ public LicensingException(LicensingResult result) { super(result.getMessage(), result.getException()); this.diagnostic = result; } + /** + * @since 0.4.0 + */ public final LicensingResult getResult() { return diagnostic; } diff --git a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingReporter.java b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingReporter.java index 1fe771527..b2ecc3fc2 100644 --- a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingReporter.java +++ b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingReporter.java @@ -23,6 +23,7 @@ public interface LicensingReporter { * Log the result * * @param result + * @since 0.4.0 */ void logResult(LicensingResult result); @@ -30,6 +31,7 @@ public interface LicensingReporter { * Post the result (asynchronous delivery) * * @param result + * @since 0.4.0 */ void postResult(LicensingResult result); @@ -37,6 +39,7 @@ public interface LicensingReporter { * Send the result (synchronous delivery) * * @param result + * @since 0.4.0 */ void sendResult(LicensingResult result); diff --git a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingResult.java b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingResult.java index a9b2a9418..4b15e12c8 100644 --- a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingResult.java +++ b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/LicensingResult.java @@ -22,60 +22,82 @@ public interface LicensingResult { /** * The bit mask value 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 */ Iterable getAttachmentKeys(); @@ -85,11 +107,15 @@ public interface LicensingResult { * @param key the key whose associated value is to be returned * @return the attached object or null 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 */ Iterable getChildren(); From b3cd99542a3f729be7496d78888882f510e68c92 Mon Sep 17 00:00:00 2001 From: "elena.parovyshnaya" Date: Fri, 8 Nov 2019 15:45:44 +0300 Subject: [PATCH 2/2] 547289 - Provide javadoc for org.eclipse.passage.lic.api package -- finish lic.api package-info draft Signed-off-by: Elena Parovyshnaia --- .../eclipse/passage/lic/api/package-info.java | 93 ++++++++++++------- 1 file changed, 59 insertions(+), 34 deletions(-) diff --git a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/package-info.java b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/package-info.java index df61e4620..9791c604f 100644 --- a/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/package-info.java +++ b/bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/package-info.java @@ -14,7 +14,8 @@ /** *

Access Management

*

In a sentence

- * 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. *

@@ -25,41 +26,47 @@ * Here Passage invokes AM to define, can the user exploit the feature or not. *

* - *
    - *
  1. AM uses {@code Requirement}s to define at runtime, which feature in a program is under licensing. + *
      The whole process from can the user use the feature query to an answer is called access cycle, + * and it consists of 5 steps. + *
    1. requirements resolution
      + * AM uses {@code Requirement}s to define at runtime, which feature in a program is under licensing. * These {@code Requirement}s are given by the precise installation of a program under licensing. * So the first thing AM does is finding out, is the actual program installation possesses any * protect this feature instructions in the first place. * To do so, AM appeals to all registered {@code RequirementResolver}s and gets a set of {@code Requirement}s * for further analysis
    2. * - *
    3. Then AM needs to figure out, what the license that the user has, allows to do. + *
    4. conditions mining
      + * Then AM needs to figure out, what the license that the user has, allows to do. * AM goes to each of {@code ConditionMiner}s it have at ones disposal * and gets set of {@code LicensingCondition}s. * {@code ConditionMiner}s look for them in the license files, on a floating server or mining sources of other types. *
    5. * - *
    6. These {@code Condition}s are static definitions of which functions can be executed under which terms. + *
    7. conditions evaluation
      + * These {@code Condition}s are static definitions of which functions can be executed under which terms. * At a program runtime AM evaluates each {@code Condition} to a precise notion of * has this {@code Condition} been met at the program runtime or not. * The fact condition terms are currently met is expressed by a time-limited {@code Permission}. * So, at this step, for each {@code Condition} AM asks all {@code PermissionEmitter}s if someone can issue * a {@code Permission} for this {@code Condition}.
    8. * - *
    9. At this point AM has both - * actual {@link org.eclipse.passage.lic.api.requirements.LicensingRequirement}s - * and valid {@link org.eclipse.passage.lic.api.access.FeaturePermission}s. - * This information is enough to make a decision about the start-up question: can the user access to the feature now. - * Here {@link org.eclipse.passage.lic.api.access.PermissionExaminer} comes to play: it goes through - * {@link org.eclipse.passage.lic.api.access.FeaturePermission}s and if it satisfies any of - * {@link org.eclipse.passage.lic.api.requirements.LicensingRequirement}, the latter one is considered satisfied and does not participate in further actions. - * All unsatisfied {@link org.eclipse.passage.lic.api.requirements.LicensingRequirement}s left at the and of the work, are translated to a set of - * {@link org.eclipse.passage.lic.api.restrictions.RestrictionVerdict}s.
    10. + *
    11. permission examining
      + * At this point AM has both actual {@code LicensingRequirement}s and valid {@code FeaturePermission}s. + * This information is enough to make a decision about the start-up question: + * can the user access to the feature now.
      + * Here {@code PermissionExaminer} comes to play: it goes through + * {@code FeaturePermission}s and checks if any of them satisfies some of {@code LicensingRequirement}, + * and then this latter ones are considered satisfied and do not participate in further actions. + * All unsatisfied {@code LicensingRequirement}s left at the end of the work, are translated to a set of + * {@code RestrictionVerdict}s.
    12. * * - *
    13. If here AM has an empty set of {@link org.eclipse.passage.lic.api.restrictions.RestrictionVerdict}s (all {@link org.eclipse.passage.lic.api.requirements.LicensingRequirement}s are satisfied), - * then the user can access the feature. Otherwise, some actions must be taken, and each verdict describes such an action. - * {@link org.eclipse.passage.lic.api.restrictions.RestrictionExecutor} is the service responsible for these actions execution: + *
    14. restriction execution
      + * If here AM has an empty set of {@code RestrictionVerdict}s (all {@code LicensingRequirement}s are satisfied), + * then the user can access the feature. Otherwise, some actions must be taken, + * and each {@code RestrictionVerdict} describes such an action. + * {@code RestrictionExecutor} is the service responsible for these actions execution: * if can popup a warning, expose license dialog or even shut the whole program down.
    15. *
    *

    @@ -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.

    - *

    - *

    + *

    + *

    *

    2. Conditions

    *

    Where do they come from?

    *

    {@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. *

    - *

    - *

    + *

    + *

    *

    3. Permissions

    *

    Where do they come from?

    *

    {@code Permission} are created by Passage at runtime as a result of a {@code Condition} evaluation. @@ -126,23 +133,41 @@ *

    *

    *

    4. Permission examining

    - *

    Where do they come from?

    - *

    - *

    Where do they come from?

    - *

    - *

    >How to get them?

    - *

    + *

    Who does the examining?

    + *

    The process of examining must be implemented by an instance of {@link org.eclipse.passage.lic.api.access.PermissionExaminer}, + * registered in the system properly.

    + *

    How the examining is performed?

    + *

    {@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.

    + *

    What is the result of the examining?

    + *

    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.

    *

    *

    *

    4. Restriction execution

    - *

    Where do they come from?

    - *

    - *

    Where do they come from?

    - *

    - *

    >How to get them?

    - *

    + *

    Who does the execution?

    + *

    There can be several instances of {@link org.eclipse.passage.lic.api.restrictions.RestrictionExecutor} interface.

    + *

    How the execution is performed?

    + *

    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.

    + *

    What is the result of the execution?

    + *

    {@code Executor} chose a behaviour according to the {@code restriction level} of the {@code restriction} under processing.

    + *
      This can be, for example, one of the following + *
    • {@code info} means an information message somehow will be exposed to the user without pausing the current user's workflow
    • + *
    • {@code warn} will pause the user workflow and explain license insufficiency, for instance by a license dialog
    • + *
    • {@code error} totally prohibits to use the feature under licensing, so the current workflow will be stopped
    • + *
    • {@code fatal} prescribes to destroy the whole environment, close the program
    • + *
    * * @since 0.4.0 */ -package org.eclipse.passage.lic.api; \ No newline at end of file +package org.eclipse.passage.lic.api;