Merge pull request #50 from eparovyshnaya/547293

547293 Provide javadoc for org.eclipse.passage.lic.api.io package

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/io/KeyKeeper.java

@@ -23,14 +23,15 @@
  * @since 0.4.0
  */
 public interface KeyKeeper {
-	
+
 	/**
-	 * 
-	 * @param configuration
+	 * Create a stream for key reading
+	 *
+	 * @param configuration general licensing configuration of a running product
 	 * @return the stream to read the key
-	 * @throws IOException
+	 * @throws IOException in case of any file system operation misbehaviour
+	 * @since 0.4.0
 	 */
-
 	InputStream openKeyStream(LicensingConfiguration configuration) throws IOException;
 
 }

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/io/KeyKeeperRegistry.java

@@ -12,19 +12,44 @@
  *******************************************************************************/
 package org.eclipse.passage.lic.api.io;
 
-import java.util.Map;
-
 import org.eclipse.passage.lic.api.LicensingConfiguration;
 
+import java.util.Map;
+
 /**
+ * Registry for {@link KeyKeeper} instances available at runtime.
+ *
  * @since 0.4.0
  */
 public interface KeyKeeperRegistry {
 
+	/**
+	 * Get a {@link KeyKeeper} for the {@code configuration}
+	 *
+	 * @param configuration general licensing configuration of running product
+	 * @since 0.4.0
+	 */
 	KeyKeeper getKeyKeeper(LicensingConfiguration configuration);
 
+	/**
+	 * Register the given {@code keyKeeper} for a {@code LicensingConfiguration},
+	 * created from the given {@code properties}.
+	 *
+	 * @param keyKeeper  instance to be registered
+	 * @param properties source information for {@code LicensingConfiguration} creation
+	 * @see LicensingConfiguration
+	 * @since 0.4.0
+	 */
 	void registerKeyKeeper(KeyKeeper keyKeeper, Map<String, Object> properties);
 
+	/**
+	 * Unregister the given {@code keyKeeper}. The {@code keyKeeper} will no longer available on
+	 * {@link #getKeyKeeper(LicensingConfiguration)} invocation
+	 *
+	 * @param keyKeeper  instance to be unregistered
+	 * @see LicensingConfiguration
+	 * @since 0.4.0
+	 */
 	void unregisterKeyKeeper(KeyKeeper keyKeeper, Map<String, Object> properties);
 
 }

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/io/StreamCodec.java

@@ -25,20 +25,58 @@
  */
 public interface StreamCodec {
 
+	/**
+	 * Key of encoding algorithm.
+	 *
+	 * @since 0.4.0
+	 */
 	String getKeyAlgo();
 
+	/**
+	 * Encoding key size.
+	 *
+	 * @since 0.4.0
+	 */
 	int getKeySize();
 
+	/**
+	 * Create a public/private keys pair and store them to {@code publicKeyPath} and {@code privateKeyPath} respectively.
+	 *
+	 * @param publicKeyPath  file system path for <i>public key</i> to be generated
+	 * @param privateKeyPath file system path for <i>private key</i> to be generated
+	 * @param username       of the keys owner user
+	 * @param password       of the keys owner user
+	 * @throws IOException in case of any i/o misbehaviour
+	 * @since 0.4.0
+	 */
 	void createKeyPair(String publicKeyPath, String privateKeyPath, String username, String password)
 			throws IOException;
 
+	/**
+	 * Encode {@code input} stream data with a private key retrieved form the given {@code key} stream.
+	 * Fill {@code output} stream with the encoded data.
+	 *
+	 * @param input    source of data to be encoded
+	 * @param output   target stream to place encoded data into
+	 * @param key      source for a private key
+	 * @param username of the private key owner user
+	 * @param password of the private key owner user
+	 * @throws IOException in case of any i/o misbehaviour
+	 * @since 0.4.0
+	 */
 	void encodeStream(InputStream input, OutputStream output, InputStream key, String username, String password)
 			throws IOException;
 
+	/**
+	 * Decode the {@code input} stream with the <i>public key</i> and store decoded data to {@code output} stream.
+	 *
+	 * @param input  source stream with encoded data
+	 * @param output target stream for decoded data
+	 * @param key    stream containing the <i>public key</i> for decoding
+	 * @param digest expected digest for еру public key source stream {@code key} to be validated prior decoding
+	 * @throws IOException in case of any i/o denial or misbehaviour
+	 * @since 0.4.0
+	 */
 	Object decodeStream(InputStream input, OutputStream output, InputStream key, byte[] digest) throws IOException;
 
-//	LicensingResult decode(InputStream input, OutputStream output, InputStream key, byte[] digest);
-//
-//	LicensingResult encode(InputStream input, OutputStream output, InputStream key, String username, String password);
-
 }

bundles/org.eclipse.passage.lic.api/src/org/eclipse/passage/lic/api/io/StreamCodecRegistry.java

@@ -17,14 +17,39 @@
 import org.eclipse.passage.lic.api.LicensingConfiguration;
 
 /**
+ * Registry for {@link StreamCodec}s available at runtime
+ *
  * @since 0.4.0
  */
 public interface StreamCodecRegistry {
 
+	/**
+	 * Get a {@link StreamCodec} for the given {@code configuration}
+	 *
+	 * @param configuration general licensing configuration for running product
+	 * @since 0.4.0
+	 */
 	StreamCodec getStreamCodec(LicensingConfiguration configuration);
 
+	/**
+	 * Register the given {@code streamCodec} for a {@code LicensingConfiguration},
+	 * created from the given {@code properties}.
+	 *
+	 * @param streamCodec  instance to be registered
+	 * @param properties source information for {@code LicensingConfiguration} creation
+	 * @see LicensingConfiguration
+	 * @since 0.4.0
+	 */
 	void registerStreamCodec(StreamCodec streamCodec, Map<String, Object> properties);
 
+	/**
+	 * Unregister the given {@code streamCodec}. The {@code streamCodec} will no longer available on
+	 * {@link #getStreamCodec(LicensingConfiguration)} invocation
+	 *
+	 * @param streamCodec  instance to be unregistered
+	 * @see LicensingConfiguration
+	 * @since 0.4.0
+	 */
 	void unregisterStreamCodec(StreamCodec streamCodec, Map<String, Object> properties);
 
 }