some cleanup and documentation of *Operation classes

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/BaseOperation.java

@@ -10,7 +10,7 @@ import org.sufficientlysecure.keychain.service.PassphraseCacheService;
 
 import java.util.concurrent.atomic.AtomicBoolean;
 
-public class BaseOperation implements PassphraseCacheInterface {
+public abstract class BaseOperation implements PassphraseCacheInterface {
 
     final public Context mContext;
     final public Progressable mProgressable;
@@ -18,7 +18,28 @@ public class BaseOperation implements PassphraseCacheInterface {
 
     final public ProviderHelper mProviderHelper;
 
-    // TODO do we really need the context in these operations?
+    /** An abstract base class for all *Operation classes. It provides a number
+     * of common methods for progress, cancellation and passphrase cache handling.
+     *
+     * An "operation" in this sense is a high level operation which is called
+     * by the KeychainIntentService or OpenPgpService services. Concrete
+     * subclasses of this class should implement either a single or a group of
+     * related operations. An operation must rely solely on its input
+     * parameters for operation specifics. It should also write a log of its
+     * operation using the OperationLog class, and return an OperationResult
+     * subclass of its specific type.
+     *
+     * An operation must *not* throw exceptions of any kind, errors should be
+     * handled as part of the OperationResult! Consequently, all handling of
+     * errors in KeychainIntentService and OpenPgpService should consist of
+     * informational rather than operational means.
+     *
+     * Note that subclasses of this class should be either Android- or
+     * BouncyCastle-related, and use as few imports from the other type as
+     * possible.  A class with Pgp- prefix is considered BouncyCastle-related,
+     * if there is no prefix it is considered Android-related.
+     *
+     */
     public BaseOperation(Context context, ProviderHelper providerHelper, Progressable progressable) {
         this.mContext = context;
         this.mProgressable = progressable;
@@ -26,7 +47,8 @@ public class BaseOperation implements PassphraseCacheInterface {
         mCancelled = null;
     }
 
-    public BaseOperation(Context context, ProviderHelper providerHelper, Progressable progressable, AtomicBoolean cancelled) {
+    public BaseOperation(Context context, ProviderHelper providerHelper,
+                         Progressable progressable, AtomicBoolean cancelled) {
         mContext = context;
         mProgressable = progressable;
         mProviderHelper = providerHelper;

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CertifyOperation.java

@@ -21,6 +21,15 @@ import org.sufficientlysecure.keychain.ui.util.KeyFormattingUtils;
 import java.util.ArrayList;
 import java.util.concurrent.atomic.AtomicBoolean;
 
+/** An operation which implements a high level user id certification operation.
+ *
+ * This operation takes a specific CertifyActionsParcel as its input. These
+ * contain a masterKeyId to be used for certification, and a list of
+ * masterKeyIds and related user ids to certify.
+ *
+ * @see CertifyActionsParcel
+ *
+ */
 public class CertifyOperation extends BaseOperation {
 
     public CertifyOperation(Context context, ProviderHelper providerHelper, Progressable progressable, AtomicBoolean cancelled) {

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/DeleteOperation.java

@@ -12,6 +12,14 @@ import org.sufficientlysecure.keychain.provider.ProviderHelper;
 import org.sufficientlysecure.keychain.service.ContactSyncAdapterService;
 import org.sufficientlysecure.keychain.ui.util.KeyFormattingUtils;
 
+/** An operation which implements a high level keyring delete operation.
+ *
+ * This operation takes a list of masterKeyIds as input, deleting all
+ * corresponding public keyrings from the database. Secret keys can
+ * be deleted as well, but only explicitly and individually, not as
+ * a list.
+ *
+ */
 public class DeleteOperation extends BaseOperation {
 
     public DeleteOperation(Context context, ProviderHelper providerHelper, Progressable progressable) {

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/ImportExportOperation.java

@@ -57,13 +57,30 @@ import java.util.ArrayList;
 import java.util.Iterator;
 import java.util.concurrent.atomic.AtomicBoolean;
 
+/** An operation class which implements high level import and export
+ * operations.
+ *
+ * This class receivs a source and/or destination of keys as input and performs
+ * all steps for this import or export.
+ *
+ * For the import operation, the only valid source is an Iterator of
+ * ParcelableKeyRing, each of which must contain exactly a single keyring
+ * encoded as bytes.
+ *
+ * For the export operation, the input consists of a set of key ids and
+ * either the name of a file or an output uri to write to.
+ *
+ * TODO rework uploadKeyRingToServer
+ *
+ */
 public class ImportExportOperation extends BaseOperation {
 
     public ImportExportOperation(Context context, ProviderHelper providerHelper, Progressable progressable) {
         super(context, providerHelper, progressable);
     }
 
-    public ImportExportOperation(Context context, ProviderHelper providerHelper, Progressable progressable, AtomicBoolean cancelled) {
+    public ImportExportOperation(Context context, ProviderHelper providerHelper,
+                                 Progressable progressable, AtomicBoolean cancelled) {
         super(context, providerHelper, progressable, cancelled);
     }
 

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerify.java

@@ -102,7 +102,6 @@ public class PgpDecryptVerify extends BaseOperation {
         // mandatory parameter
         private Context mContext;
         private ProviderHelper mProviderHelper;
-        private PassphraseCacheInterface mPassphraseCache;
         private InputData mData;
         private OutputStream mOutStream;
 

OpenKeychain/src/main/java/org/sufficientlysecure/keychain/service/KeychainIntentService.java

@@ -33,7 +33,6 @@ import org.sufficientlysecure.keychain.operations.DeleteOperation;
 import org.sufficientlysecure.keychain.operations.results.DeleteResult;
 import org.sufficientlysecure.keychain.operations.results.ExportResult;
 import org.sufficientlysecure.keychain.pgp.exception.PgpKeyNotFoundException;
-import org.sufficientlysecure.keychain.provider.ProviderHelper.NotFoundException;
 import org.sufficientlysecure.keychain.operations.results.CertifyResult;
 import org.sufficientlysecure.keychain.util.FileHelper;
 import org.sufficientlysecure.keychain.util.ParcelableFileCache.IteratorWithSize;
@@ -45,7 +44,6 @@ import org.sufficientlysecure.keychain.keyimport.Keyserver;
 import org.sufficientlysecure.keychain.keyimport.ParcelableKeyRing;
 import org.sufficientlysecure.keychain.pgp.CanonicalizedPublicKeyRing;
 import org.sufficientlysecure.keychain.pgp.CanonicalizedSecretKeyRing;
-import org.sufficientlysecure.keychain.pgp.PassphraseCacheInterface;
 import org.sufficientlysecure.keychain.pgp.PgpDecryptVerify;
 import org.sufficientlysecure.keychain.operations.results.DecryptVerifyResult;
 import org.sufficientlysecure.keychain.pgp.PgpHelper;
@@ -73,7 +71,6 @@ import org.sufficientlysecure.keychain.util.ProgressScaler;
 
 import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
-import java.io.File;
 import java.io.FileNotFoundException;
 import java.io.IOException;
 import java.io.OutputStream;