Add javadoc and fix checkstyle issues

2018-07-05 13:44:40 +02:00 · 2018-07-05 13:44:40 +02:00 · cf4129f932
parent 3262582de9
commit cf4129f932
6 changed files with 71 additions and 28 deletions
--- a/smack-integration-test/src/main/java/org/jivesoftware/smackx/openpgp/BasicOpenPgpInstantMessagingIntegrationTest.java
+++ b/smack-integration-test/src/main/java/org/jivesoftware/smackx/openpgp/BasicOpenPgpInstantMessagingIntegrationTest.java
@ -27,11 +27,11 @@ import org.jivesoftware.smack.packet.Message;
 import org.jivesoftware.smack.util.FileUtils;
 import org.jivesoftware.smack.util.StringUtils;
 import org.jivesoftware.smackx.ox.OXInstantMessagingManager;
+import org.jivesoftware.smackx.ox.OpenPgpContact;
 import org.jivesoftware.smackx.ox.OpenPgpManager;
 import org.jivesoftware.smackx.ox.OpenPgpV4Fingerprint;
 import org.jivesoftware.smackx.ox.bouncycastle.FileBasedPainlessOpenPgpStore;
 import org.jivesoftware.smackx.ox.bouncycastle.PainlessOpenPgpProvider;
-import org.jivesoftware.smackx.ox.OpenPgpContact;
 import org.jivesoftware.smackx.ox.element.SigncryptElement;
 import org.jivesoftware.smackx.ox.listener.OxMessageListener;
 import org.jivesoftware.smackx.ox.util.PubSubDelegate;
--- a/smack-openpgp-bouncycastle/src/test/java/org/jivesoftware/smackx/ox/bouncycastle/DryOxEncryptionTest.java
+++ b/smack-openpgp-bouncycastle/src/test/java/org/jivesoftware/smackx/ox/bouncycastle/DryOxEncryptionTest.java
@ -35,9 +35,9 @@ import org.jivesoftware.smack.XMPPConnection;
 import org.jivesoftware.smack.packet.ExtensionElement;
 import org.jivesoftware.smack.packet.Message;
 import org.jivesoftware.smack.util.FileUtils;
+import org.jivesoftware.smackx.ox.OpenPgpContact;
 import org.jivesoftware.smackx.ox.OpenPgpV4Fingerprint;
 import org.jivesoftware.smackx.ox.TestKeys;
-import org.jivesoftware.smackx.ox.OpenPgpContact;
 import org.jivesoftware.smackx.ox.element.OpenPgpContentElement;
 import org.jivesoftware.smackx.ox.element.OpenPgpElement;
 import org.jivesoftware.smackx.ox.element.PubkeyElement;
--- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OXInstantMessagingManager.java
+++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OXInstantMessagingManager.java
@ -39,6 +39,7 @@ import org.jivesoftware.smackx.ox.exception.MissingOpenPgpKeyPairException;
 import org.jivesoftware.smackx.ox.exception.SmackOpenPgpException;
 import org.jivesoftware.smackx.ox.listener.OxMessageListener;
 import org.jivesoftware.smackx.ox.listener.internal.SigncryptElementReceivedListener;
+
 import org.jxmpp.jid.BareJid;

 /**
--- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpContact.java
+++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpContact.java
@ -46,6 +46,7 @@ import org.jivesoftware.smackx.ox.exception.MissingUserIdOnKeyException;
 import org.jivesoftware.smackx.ox.exception.SmackOpenPgpException;
 import org.jivesoftware.smackx.ox.util.DecryptedBytesAndMetadata;
 import org.jivesoftware.smackx.ox.util.PubSubDelegate;
+
 import org.jxmpp.jid.BareJid;
 import org.jxmpp.jid.Jid;
 import org.xmlpull.v1.XmlPullParserException;
@ -152,8 +153,8 @@ public class OpenPgpContact {
    /**
     * Update any missing or outdated keys based on the given {@link PublicKeysListElement}.
     *
-     * @param metadata
-     * @throws SmackOpenPgpException
+     * @param metadata {@link PublicKeysListElement}
+     * @throws SmackOpenPgpException in case the available keys cannot be fetched
     */
    public void updateKeys(PublicKeysListElement metadata)
            throws SmackOpenPgpException {
@ -170,7 +171,7 @@ public class OpenPgpContact {
                    unfetchableKeys.remove(fingerprint);
                } catch (IOException | XMPPException.XMPPErrorException | SmackException | InterruptedException |
                        SmackOpenPgpException | MissingUserIdOnKeyException | NullPointerException e) {
-                    LOGGER.log(Level.WARNING, "Could not update key " + fingerprint + " of " +getJid());
+                    LOGGER.log(Level.WARNING, "Could not update key " + fingerprint + " of " + getJid());
                    unfetchableKeys.put(fingerprint, e);
                }
            }
--- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpManager.java
+++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpManager.java
@ -139,6 +139,12 @@ public final class OpenPgpManager extends Manager {
        this.provider = provider;
    }

+    /**
+     * Get our OpenPGP self.
+     *
+     * @return self
+     * @throws SmackException.NotLoggedInException if we are not logged in
+     */
    public OpenPgpSelf getOpenPgpSelf() throws SmackException.NotLoggedInException {
        throwIfNotAuthenticated();

@ -157,11 +163,14 @@ public final class OpenPgpManager extends Manager {
     * @throws NoSuchAlgorithmException if we are missing an algorithm to generate a fresh key pair.
     * @throws NoSuchProviderException if we are missing a suitable {@link java.security.Provider}.
     * @throws SmackOpenPgpException if something bad happens during key generation/loading.
-     * @throws InterruptedException
-     * @throws PubSubException.NotALeafNodeException
-     * @throws XMPPException.XMPPErrorException
-     * @throws SmackException.NotConnectedException
-     * @throws SmackException.NoResponseException
+     * @throws InterruptedException if the connection gets interrupted.
+     * @throws PubSubException.NotALeafNodeException if one of the PubSub nodes is not a {@link LeafNode}.
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
+     * @throws SmackException.NotConnectedException if we are not connected.
+     * @throws SmackException.NoResponseException if the server doesn't respond.
+     * @throws IOException IO is dangerous.
+     * @throws InvalidAlgorithmParameterException if illegal algorithm parameters are used for key generation.
+     * @throws SmackException.NotLoggedInException if we are not logged in.
     */
    public void announceSupportAndPublish()
            throws NoSuchAlgorithmException, NoSuchProviderException, SmackOpenPgpException,
@ -196,6 +205,17 @@ public final class OpenPgpManager extends Manager {
                .addFeature(PEP_NODE_PUBLIC_KEYS_NOTIFY);
    }

+    /**
+     * Generate a fresh OpenPGP key pair and import it.
+     *
+     * @param ourJid our {@link BareJid}.
+     * @return {@link OpenPgpV4Fingerprint} of the generated key.
+     * @throws NoSuchAlgorithmException if the JVM doesn't support one of the used algorithms.
+     * @throws IOException IO is dangerous.
+     * @throws InvalidAlgorithmParameterException if the used algorithm parameters are invalid.
+     * @throws NoSuchProviderException if we are missing a cryptographic provider.
+     * @throws SmackOpenPgpException in case of an OpenPGP error.
+     */
    public OpenPgpV4Fingerprint generateAndImportKeyPair(BareJid ourJid)
            throws NoSuchAlgorithmException, IOException, InvalidAlgorithmParameterException, NoSuchProviderException,
            SmackOpenPgpException {
@ -250,10 +270,10 @@ public final class OpenPgpManager extends Manager {
     *
     * @param connection
     * @return true, if the server supports secret key backups, otherwise false.
-     * @throws XMPPException.XMPPErrorException
-     * @throws SmackException.NotConnectedException
-     * @throws InterruptedException
-     * @throws SmackException.NoResponseException
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
+     * @throws SmackException.NotConnectedException if we are not connected.
+     * @throws InterruptedException if the connection is interrupted.
+     * @throws SmackException.NoResponseException if the server doesn't respond.
     */
    public static boolean serverSupportsSecretKeyBackups(XMPPConnection connection)
            throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException,
@ -269,11 +289,15 @@ public final class OpenPgpManager extends Manager {
     *
     * @param displayCodeCallback callback, which will receive the backup password used to encrypt the secret key.
     * @param selectKeyCallback callback, which will receive the users choice of which keys will be backed up.
-     * @throws InterruptedException
-     * @throws PubSubException.NotALeafNodeException
-     * @throws XMPPException.XMPPErrorException
-     * @throws SmackException.NotConnectedException
-     * @throws SmackException.NoResponseException
+     * @throws InterruptedException if the connection is interrupted.
+     * @throws PubSubException.NotALeafNodeException if the private node is not a {@link LeafNode}.
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
+     * @throws SmackException.NotConnectedException if we are not connected.
+     * @throws SmackException.NoResponseException if the server doesn't respond.
+     * @throws SmackException.NotLoggedInException if we are not logged in.
+     * @throws SmackOpenPgpException in case of an OpenPGP exception.
+     * @throws IOException IO is dangerous.
+     * @throws SmackException.FeatureNotSupportedException if the server doesn't support the PubSub whitelist access model.
     */
    public void backupSecretKeyToServer(DisplayBackupCodeCallback displayCodeCallback,
                                        SecretKeyBackupSelectionCallback selectKeyCallback)
@ -299,10 +323,11 @@ public final class OpenPgpManager extends Manager {
    /**
     * Delete the private {@link LeafNode} containing our secret key backup.
     *
-     * @throws XMPPException.XMPPErrorException
-     * @throws SmackException.NotConnectedException
-     * @throws InterruptedException
-     * @throws SmackException.NoResponseException
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
+     * @throws SmackException.NotConnectedException if we are not connected.
+     * @throws InterruptedException if the connection gets interrupted.
+     * @throws SmackException.NoResponseException if the server doesn't respond.
+     * @throws SmackException.NotLoggedInException if we are not logged in.
     */
    public void deleteSecretKeyServerBackup()
            throws XMPPException.XMPPErrorException, SmackException.NotConnectedException, InterruptedException,
@ -316,11 +341,11 @@ public final class OpenPgpManager extends Manager {
     *
     * @param codeCallback callback for prompting the user to provide the secret backup code.
     * @param selectionCallback callback allowing the user to select a secret key which will be restored.
-     * @throws InterruptedException
-     * @throws PubSubException.NotALeafNodeException
-     * @throws XMPPException.XMPPErrorException
-     * @throws SmackException.NotConnectedException
-     * @throws SmackException.NoResponseException
+     * @throws InterruptedException if the connection gets interrupted.
+     * @throws PubSubException.NotALeafNodeException if the private node is not a {@link LeafNode}.
+     * @throws XMPPException.XMPPErrorException in case of an XMPP protocol error.
+     * @throws SmackException.NotConnectedException if we are not connected.
+     * @throws SmackException.NoResponseException if the server doesn't respond.
     * @throws SmackOpenPgpException if something goes wrong while restoring the secret key.
     * @throws InvalidBackupCodeException if the user-provided backup code is invalid.
     */
--- a/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpSelf.java
+++ b/smack-openpgp/src/main/java/org/jivesoftware/smackx/ox/OpenPgpSelf.java
@ -1,3 +1,19 @@
+/**
+ *
+ * Copyright 2018 Paul Schaub.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.jivesoftware.smackx.ox;

 import org.jivesoftware.smack.XMPPConnection;