From be66f2e38069c5ee03d0a9300a864e3d480576ae Mon Sep 17 00:00:00 2001
From: Lukas Niemeier <lukas.niemeier@sap.com>
Date: Tue, 29 Oct 2013 22:26:19 +0100
Subject: [PATCH] # added some missing comments

---
 .../DeviceConfigurationMatcher.java           | 48 +++++++++++++++----
 .../impl/DeviceConfigurationMapImpl.java      | 17 +++++--
 .../impl/DeviceConfigurationMatcherAny.java   |  3 ++
 .../impl/DeviceConfigurationMatcherMulti.java |  3 ++
 .../DeviceConfigurationMatcherSingle.java     |  3 ++
 5 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/DeviceConfigurationMatcher.java b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/DeviceConfigurationMatcher.java
index 4bbcab44985..387f82d6d0d 100644
--- a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/DeviceConfigurationMatcher.java
+++ b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/DeviceConfigurationMatcher.java
@@ -3,30 +3,62 @@ package com.sap.sailing.domain.base.configuration;
 import java.io.Serializable;
 
 import com.sap.sailing.domain.base.IsManagedBySharedDomainFactory;
+import com.sap.sailing.domain.base.configuration.impl.DeviceConfigurationMapImpl;
 
+/**
+ * <p>
+ * Classes implementing this interface are matching {@link DeviceConfigurationIdentifier}s to associate them with a
+ * {@link DeviceConfiguration}.
+ * </p>
+ * 
+ * <p>The rank (see {@link DeviceConfigurationMatcher#getMatchingRank()}) is used as a priority when multiple matchers
+ *  are matching a {@link DeviceConfigurationIdentifier} (see also {@link DeviceConfigurationMapImpl}).</p> 
+ */
 public interface DeviceConfigurationMatcher extends IsManagedBySharedDomainFactory, Serializable {
     final static int RANK_SINGLE = 1;
     final static int RANK_MULTI = 2;
     final static int RANK_ANY = 3;
-    
+
     public enum Type {
-        SINGLE(RANK_SINGLE),
-        MULTI(RANK_MULTI),
-        ANY(RANK_ANY);
-        
+        SINGLE(RANK_SINGLE), MULTI(RANK_MULTI), ANY(RANK_ANY);
+
         private int matchingRank;
-        
+
         private Type(int rank) {
             this.matchingRank = rank;
         }
-        
+
         public int getRank() {
             return matchingRank;
         }
     }
-    
+
+    /**
+     * Returns the kind of matching used by this matcher.
+     * 
+     * @return the {@link Type}.
+     */
     Type getMatcherType();
+
+    /**
+     * Gets the matcher's rank.
+     * 
+     * @return the rank.
+     */
     int getMatchingRank();
+
+    /**
+     * Returns <code>true</code> if this {@link DeviceConfigurationMatcher} matches the given
+     * {@link DeviceConfigurationIdentifier}; otherwise <code>false</code>.
+     * 
+     * @param identifier
+     */
     boolean matches(DeviceConfigurationIdentifier identifier);
+
+    /**
+     * Gets this matcher's identifier.
+     * 
+     * @return the identifier.
+     */
     Serializable getMatcherIdentifier();
 }
diff --git a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMapImpl.java b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMapImpl.java
index b15f290ae13..fe420eb5a44 100644
--- a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMapImpl.java
+++ b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMapImpl.java
@@ -1,19 +1,30 @@
 package com.sap.sailing.domain.base.configuration.impl;
 
+import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
 
 import com.sap.sailing.domain.base.configuration.DeviceConfiguration;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationIdentifier;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationMatcher;
 
+/**
+ * <p>
+ * Helper class providing a {@link Map} of {@link DeviceConfigurationMatcher}s associated with their
+ * {@link DeviceConfiguration}.
+ * </p>
+ * 
+ * <p>
+ * When searching for a match, the highest ranked {@link DeviceConfigurationMatcher} (i.e. lowest number) wins.
+ * </p>
+ */
 public class DeviceConfigurationMapImpl extends ConcurrentHashMap<DeviceConfigurationMatcher, DeviceConfiguration> {
 
     private static final long serialVersionUID = -8009136964737670452L;
-    
+
     private interface Action {
         DeviceConfiguration call(DeviceConfigurationMatcher matcher);
     }
-    
+
     public DeviceConfiguration getByMatch(DeviceConfigurationIdentifier key) {
         return doByMatch(key, new Action() {
             @Override
@@ -31,7 +42,7 @@ public class DeviceConfigurationMapImpl extends ConcurrentHashMap<DeviceConfigur
             }
         });
     }
-    
+
     private DeviceConfiguration doByMatch(DeviceConfigurationIdentifier key, Action action) {
         DeviceConfigurationMatcher match = null;
         for (Entry<DeviceConfigurationMatcher, DeviceConfiguration> entry : entrySet()) {
diff --git a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherAny.java b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherAny.java
index 5d748b32365..8512e1c7b6f 100644
--- a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherAny.java
+++ b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherAny.java
@@ -8,6 +8,9 @@ import com.sap.sailing.domain.base.SharedDomainFactory;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationIdentifier;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationMatcher;
 
+/**
+ * Matches all {@link DeviceConfigurationIdentifier}.
+ */
 public enum DeviceConfigurationMatcherAny implements DeviceConfigurationMatcher {
     INSTANCE;
 
diff --git a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherMulti.java b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherMulti.java
index e1898af6b02..dc4c67edc5f 100644
--- a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherMulti.java
+++ b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherMulti.java
@@ -10,6 +10,9 @@ import com.sap.sailing.domain.base.SharedDomainFactory;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationIdentifier;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationMatcher;
 
+/**
+ * Matches a set of {@link DeviceConfigurationIdentifier}s.
+ */
 public class DeviceConfigurationMatcherMulti implements DeviceConfigurationMatcher {
     
     private static final long serialVersionUID = 2372299957258702516L;
diff --git a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherSingle.java b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherSingle.java
index 32df2da8a02..510c98f276b 100644
--- a/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherSingle.java
+++ b/java/com.sap.sailing.domain.shared.android/src/com/sap/sailing/domain/base/configuration/impl/DeviceConfigurationMatcherSingle.java
@@ -8,6 +8,9 @@ import com.sap.sailing.domain.base.SharedDomainFactory;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationIdentifier;
 import com.sap.sailing.domain.base.configuration.DeviceConfigurationMatcher;
 
+/**
+ * Matches a single {@link DeviceConfigurationIdentifier}.
+ */
 public class DeviceConfigurationMatcherSingle implements DeviceConfigurationMatcher {
     
     private static final long serialVersionUID = -3662453614818373801L;