Merge pull request #48 from eparovyshnaya/547292

547292 Provide javadoc for org.eclipse.passage.lic.api.inspector package

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/inspector/FeatureCase.java

@@ -16,16 +16,40 @@
 import org.eclipse.passage.lic.api.restrictions.RestrictionVerdict;
 
 /**
+ * Pre-evaluated license coverage for a particular features subset (affected, say, by one user scenario),
+ * managed by {@code FeatureInspector}
+ *
+ * @see FeatureInspector
  * @since 0.4.0
  */
 public interface FeatureCase extends AutoCloseable {
 
+	/**
+	 * Identifiers of the features under inspection.
+	 *
+	 * @since 0.4.0
+	 */
 	Iterable<String> getFeatureIdentifiers();
 
+	/**
+	 * {@code Requirement}s resolved during the inspection
+	 *
+	 * @since 0.4.0
+	 */
 	Iterable<LicensingRequirement> getRequirements();
 
+	/**
+	 * {@code Restriction}s evaluated as the result of the inspection
+	 *
+	 * @since 0.4.0
+	 */
 	Iterable<RestrictionVerdict> getRestrictions();
 
+	/**
+	 * The case is auto-closable
+	 *
+	 * @since 0.4.0
+	 */
 	@Override
 	void close();
 

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/inspector/FeatureInspector.java

@@ -3,14 +3,37 @@
 import org.eclipse.passage.lic.api.LicensingConfiguration;
 
 /**
+ * <p>
+ * There are use cases, where all but the last step of <i>access cycle</i> are required.
+ * For those cases {@code FeatureInspector} contract implements a subset of those steps,
+ * called <i>inspection cycle</i>, in order to preliminary evaluate license coverage for a whole running product
+ * or for a particular user scenario (that affects potentially several features under licensing).
+ * </p>
+ *
  * @since 0.4.0
  */
 public interface FeatureInspector {
-
+
+	/**
+	 * General configuration of a running product
+	 *
+	 * @since 0.4.0
+	 */
 	LicensingConfiguration getLicensingConfiguration();
-
+
+	/**
+	 * Convenience method
+	 *
+	 * @see #inspectFeatures(Iterable)
+	 * @since 0.4.0
+	 */
 	FeatureCase inspectFeatures(String... identifiers);
 
+	/**
+	 * Pre-evaluates license coverage for specified features.
+	 *
+	 * @since 0.4.0
+	 */
 	FeatureCase inspectFeatures(Iterable<String> identifiers);
 
 }

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/inspector/HardwareInspector.java

@@ -12,49 +12,154 @@
  *******************************************************************************/
 package org.eclipse.passage.lic.api.inspector;
 
+import org.eclipse.passage.lic.api.conditions.LicensingCondition;
+import org.eclipse.passage.lic.api.access.PermissionEmitter;
+
 import java.io.IOException;
 import java.io.OutputStream;
 
 /**
+ * <p>Contract for a service capable to uncover and enlist current hardware details, sufficient for licensing.</p>
+ *
+ * <p>Used, for example, by {@code PermissionEmitter} on analysis of a {@code LicensingCondition},
+ * which has <i>hardware</i> {@code conditionType}. This one is expected to enlist all hardware information encoded in it's {@code conditionExpression}.
+ * Thus the {@code emitter} can check is encoded hardware information fits to the one gathered by this service.</p>
+ *
+ * @see PermissionEmitter
+ * @see LicensingCondition#getConditionType
+ * @see LicensingCondition#getConditionExpression
  * @since 0.4.0
  */
 public interface HardwareInspector {
-
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_OS_FAMILY = "os.family"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_OS_MANUFACTURER = "os.manufacturer"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_OS_VERSION = "os.version"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_OS_BUILDNUMBER = "os.buildnumber"; //$NON-NLS-1$
 
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_SYSTEM_MANUFACTURER = "system.manufacturer"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_SYSTEM_MODEL = "system.model"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_SYSTEM_SERIALNUMBER = "system.serialnumber"; //$NON-NLS-1$
 
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_BASEBOARD_MANUFACTURER = "baseboard.manufacturer"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_BASEBOARD_MODEL = "baseboard.model"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_BASEBOARD_VERSION = "baseboard.version"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_BASEBOARD_SERIALNUMBER = "baseboard.serialnumber"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_FIRMWARE_MANUFACTURER = "firmware.manufacturer"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_FIRMWARE_VERSION = "firmware.version"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_FIRMWARE_RELEASEDATE = "firmware.releasedate"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_FIRMWARE_NAME = "firmware.name"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_FIRMWARE_DESCRIPTION = "firmware.description"; //$NON-NLS-1$
 
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_CPU_VENDOR = "cpu.vendor"; //$NON-NLS-1$ ;
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_CPU_FAMILY = "cpu.family"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_CPU_MODEL = "cpu.model"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_CPU_NAME = "cpu.name"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_CPU_IDENTIFIER = "cpu.identifier"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_CPU_PROCESSORID = "cpu.processorid"; //$NON-NLS-1$
 
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_HWDISK_MODEL = "hwdisk.model"; //$NON-NLS-1$ ;
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_HWDISK_NAME = "hwdisk.name"; //$NON-NLS-1$
+	/**
+	 * @since 0.4.0
+	 */
 	String PROPERTY_HWDISK_SERIAL = "hwdisk.serial"; //$NON-NLS-1$
 
+	/**
+	 * Discovers hardware information and writes it to the {@code output}
+	 *
+	 * @param output target stream. Stays {@code opened}, closure is on the caller's side.
+	 * @since 0.4.0
+	 */
 	void dumpHardwareInfo(OutputStream output) throws IOException;
 
+	/**
+	 * Enlist names for all uncovered hardware properties.
+	 *
+	 * @since 0.4.0
+	 */
 	Iterable<String> getKnownProperties();
 
+	/**
+	 * Get a value for a named hardware information.
+	 *
+	 * @since 0.4.0
+	 */
 	String inspectProperty(String name);
 
 }