From b6c7231a7f7db860059c3af803a5ddf04aa2cb9e Mon Sep 17 00:00:00 2001 From: Vincent Breitmoser Date: Wed, 15 Oct 2014 16:57:23 +0200 Subject: some cleanup and documentation of *Operation classes --- .../keychain/operations/BaseOperation.java | 28 +++++++++++++++++++--- .../keychain/operations/CertifyOperation.java | 9 +++++++ .../keychain/operations/DeleteOperation.java | 8 +++++++ .../keychain/operations/ImportExportOperation.java | 19 ++++++++++++++- .../keychain/pgp/PgpDecryptVerify.java | 1 - .../keychain/service/KeychainIntentService.java | 3 --- 6 files changed, 60 insertions(+), 8 deletions(-) (limited to 'OpenKeychain/src/main/java/org/sufficientlysecure/keychain') diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/BaseOperation.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/BaseOperation.java index 09d7a0063..c400eb813 100644 --- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/BaseOperation.java +++ b/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; diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CertifyOperation.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CertifyOperation.java index d27221c20..2eb4c955c 100644 --- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/CertifyOperation.java +++ b/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) { diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/DeleteOperation.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/DeleteOperation.java index 00d50aa9b..124dd1aaf 100644 --- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/DeleteOperation.java +++ b/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) { diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/ImportExportOperation.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/ImportExportOperation.java index f42053bad..15d461006 100644 --- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/operations/ImportExportOperation.java +++ b/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); } diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerify.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerify.java index 7af7becb6..4f086c2a6 100644 --- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/pgp/PgpDecryptVerify.java +++ b/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; diff --git a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/service/KeychainIntentService.java b/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/service/KeychainIntentService.java index eb5ab93f7..e4a5276d5 100644 --- a/OpenKeychain/src/main/java/org/sufficientlysecure/keychain/service/KeychainIntentService.java +++ b/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; -- cgit v1.2.3