Add javadoc, suppress warnings.
authorDavid ‘Bombe’ Roden <bombe@pterodactylus.net>
Mon, 19 Sep 2011 19:32:16 +0000 (21:32 +0200)
committerDavid ‘Bombe’ Roden <bombe@pterodactylus.net>
Mon, 19 Sep 2011 19:32:16 +0000 (21:32 +0200)
src/main/java/net/pterodactylus/wotns/main/IdentityComparator.java
src/main/java/net/pterodactylus/wotns/main/IdentityTargets.java
src/main/java/net/pterodactylus/wotns/main/Resolver.java
src/main/java/net/pterodactylus/wotns/main/WoTNSPlugin.java

index c903a23..3bc8665 100644 (file)
@@ -22,14 +22,24 @@ import java.util.Comparator;
 import net.pterodactylus.wotns.freenet.wot.Identity;
 
 /**
- * TODO
+ * Contains several comparators that can be used with {@link Identity}s. At the
+ * moment only a single {@link Comparator} is defined; it sorts identities
+ * case-insensitively by name.
  *
  * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  */
 public class IdentityComparator {
 
+       /** Comparator for sorting by name. */
+       @SuppressWarnings("synthetic-access")
        public static final Comparator<Identity> NAME = new IdentityNameComparator();
 
+       /**
+        * {@link Comparator} for {@link Identity}s that sorts case-insensitively by
+        * name.
+        *
+        * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
+        */
        private static class IdentityNameComparator implements Comparator<Identity> {
 
                /**
index 54dc660..a992091 100644 (file)
@@ -26,25 +26,49 @@ import java.util.Map.Entry;
 import net.pterodactylus.wotns.freenet.wot.Identity;
 
 /**
- * TODO
+ * Scans an {@link Identity}’s properties for WoTNS targets.
  *
  * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  */
 public class IdentityTargets implements Iterable<Entry<String, String>> {
 
+       /** The identity being scanned. */
        private final Identity identity;
 
+       /** The located targets. */
        private final Map<String, String> targets = new HashMap<String, String>();
 
+       /**
+        * Creates a new target scanner for the given identity.
+        *
+        * @param identity
+        *            The identity to scan for targets
+        */
        public IdentityTargets(Identity identity) {
                this.identity = identity;
        }
 
+       //
+       // ACCESSORS
+       //
+
+       /**
+        * Returns the targets of the identity.
+        *
+        * @return The targets defined in the identity
+        */
        public Map<String, String> getTargets() {
                scanForTargets();
                return Collections.unmodifiableMap(targets);
        }
 
+       /**
+        * Returns the target with the given name.
+        *
+        * @param name
+        *            The name of the target
+        * @return The target
+        */
        public String getTarget(String name) {
                scanForTargets();
                return targets.get(name);
@@ -54,6 +78,9 @@ public class IdentityTargets implements Iterable<Entry<String, String>> {
        // PRIVATE METHODS
        //
 
+       /**
+        * Re-scans the identity for targets.
+        */
        private void scanForTargets() {
                synchronized (targets) {
                        targets.clear();
index 94a098e..66032d9 100644 (file)
@@ -35,26 +35,61 @@ import net.pterodactylus.wotns.freenet.wot.Trust;
 import freenet.keys.FreenetURI;
 
 /**
- * TODO
+ * Resolves short names as given by the user.
+ * <p>
+ * Short names generally have the syntax:
+ *
+ * <pre>
+ * identity [ ‘@’ start-of-key ] ‘/’ target [ ‘/’ file-path ]
+ * </pre>
+ * <p>
+ * Because resolving a short name is based on the <i>web</i> of trust, the ID of
+ * an own identity must be given in order to find the entry point into the web
+ * of trust. If no ID is specified, the ID of a random own identity is used. If
+ * no own identity exists, short names can not be resolved.
  *
  * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  */
 public class Resolver {
 
+       /** The logger. */
        private static final Logger logger = Logging.getLogger(Resolver.class);
 
+       /** The identity manager. */
        private final IdentityManager identityManager;
 
+       /** The ID of the own identity to use for resolving. */
        private String ownIdentityId;
 
+       /**
+        * Creates a new resolver.
+        *
+        * @param identityManager
+        *            The identity manager to use
+        */
        public Resolver(IdentityManager identityManager) {
                this.identityManager = identityManager;
        }
 
+       //
+       // ACCESSORS
+       //
+
+       /**
+        * Returns the ID of the own identity used for resolving short names.
+        *
+        * @return The ID of the own identity used for resolving
+        */
        public String getOwnIdentityId() {
                return ownIdentityId;
        }
 
+       /**
+        * Sets the ID of the own identity used for resolving short names.
+        *
+        * @param ownIdentityId
+        *            The ID of the own identity used for resolving
+        */
        public void setOwnIdentityId(String ownIdentityId) {
                this.ownIdentityId = ownIdentityId;
        }
@@ -63,6 +98,16 @@ public class Resolver {
        // ACTIONS
        //
 
+       /**
+        * Resolves a short name.
+        *
+        * @param shortUri
+        *            The short name to resolve
+        * @return The Freenet URI the short name resolves to, or {@code null} if
+        *         the short name can not be resolved
+        * @throws MalformedURLException
+        *             if the short name is malformed
+        */
        public FreenetURI resolveURI(String shortUri) throws MalformedURLException {
                int firstSlash = shortUri.indexOf('/');
                if (firstSlash == -1) {
@@ -82,6 +127,18 @@ public class Resolver {
        // PRIVATE METHODS
        //
 
+       /**
+        * Locates the identity specified by the given short name. If more than one
+        * identity matches the given pattern, the one with the highest trust is
+        * used. When calculating the trust, local and remote trust are treated
+        * equally, i.e. the higher value of either one is used.
+        *
+        * @param shortName
+        *            The short name to locate an identity for
+        * @return The located identity, or {@code null} if no identity can be
+        *         found, or if no own identity is found to use for locating an
+        *         identity
+        */
        private Identity locateIdentity(String shortName) {
                int atSign = shortName.indexOf('@');
                String identityName = shortName;
@@ -130,6 +187,12 @@ public class Resolver {
                return matchingIdentities.get(0);
        }
 
+       /**
+        * Returns a random own identity from the web of trust.
+        *
+        * @return A random own identity from the web of trust, or {@code null} if
+        *         the web of trust does not have any own identities
+        */
        private OwnIdentity getFirstOwnIdentity() {
                Set<OwnIdentity> ownIdentities = identityManager.getAllOwnIdentities();
                if (!ownIdentities.isEmpty()) {
index c495e71..83639c2 100644 (file)
@@ -35,7 +35,7 @@ import freenet.pluginmanager.FredPluginVersioned;
 import freenet.pluginmanager.PluginRespirator;
 
 /**
- * TODO
+ * Main plugin class for Web of Trust Name Service.
  *
  * @author <a href="mailto:bombe@pterodactylus.net">David ‘Bombe’ Roden</a>
  */
@@ -46,36 +46,63 @@ public class WoTNSPlugin implements FredPlugin, FredPluginL10n, FredPluginBaseL1
                Logging.setupConsoleLogging();
        }
 
+       /** The current version of the plugin. */
        private static final Version VERSION = new Version(0, 0, 7);
 
+       /** The plugin respirator. */
        private PluginRespirator pluginRespirator;
 
+       /** The l10n handler. */
        private PluginL10n l10n;
 
+       /** The web interface. */
        private WebInterface webInterface;
 
+       /** The resolver. */
        private Resolver resolver;
 
+       /** The web of trust connector. */
        private WebOfTrustConnector webOfTrustConnector;
 
+       /** The identity manager. */
        private IdentityManager identityManager;
 
        //
        // ACCESSORS
        //
 
+       /**
+        * Returns the high-level simple client for the node.
+        *
+        * @return The high-level simple client
+        */
        public HighLevelSimpleClient getHighLevelSimpleClient() {
                return pluginRespirator.getHLSimpleClient();
        }
 
+       /**
+        * Returns the toadlet container of the node.
+        *
+        * @return The toadlet container of the node
+        */
        public ToadletContainer getToadletContainer() {
                return pluginRespirator.getToadletContainer();
        }
 
+       /**
+        * Returns the identity manager.
+        *
+        * @return The identity manager
+        */
        public IdentityManager getIdentityManager() {
                return identityManager;
        }
 
+       /**
+        * Returns the resolver.
+        *
+        * @return The resolver
+        */
        public Resolver getResolver() {
                return resolver;
        }
@@ -88,7 +115,7 @@ public class WoTNSPlugin implements FredPlugin, FredPluginL10n, FredPluginBaseL1
         * {@inheritDoc}
         */
        @Override
-       public void runPlugin(PluginRespirator pluginRespirator) {
+       public void runPlugin(@SuppressWarnings("hiding") PluginRespirator pluginRespirator) {
                this.pluginRespirator = pluginRespirator;
 
                PluginConnector pluginConnector = new PluginConnector(pluginRespirator);