emailnameparser: service behaves as before in version 4.0, also for version 4.1. there is a new emailnameparser2 with a slightly different return value. it only exists in 4.1. the new service was added to not break the existing api. users are encouraged to switch, the older one is set deprecated.

Author: fabiankessler

src/main/java/org/nameapi/client/services/email/emailnameparser/EmailAddressParsingResultType.java

@@ -7,10 +7,15 @@
 public enum EmailAddressParsingResultType {
 
     /**
-     * The email address belongs to a department (eg [email protected]) or is
-     * technical (eg [email protected]).
+     * The email address belongs to a department, such as [email protected].
      */
-    FUNCTIONAL,
+    DEPARTMENT,
+
+    /**
+     * It is a technical email address for the domain, such as [email protected].
+     *
+     */
+    TECHNICAL,
 
     /**
      * The email address contains a person's initials such as [email protected].

src/main/java/org/nameapi/client/services/email/emailnameparser/EmailNameParserCommand.java

@@ -31,7 +31,10 @@
  * </p>
  *
  * <p>Names are not formatted to correct case, they are left the way they appeared in the input.</p>
+ *
+ * @deprecated use the EmailNameParser2Command
  */
+@Deprecated
 public class EmailNameParserCommand
         extends NameApiBaseCommand<SoapEmailNameParser, String, EmailNameParserResult>
 {

src/main/java/org/nameapi/client/services/email/emailnameparser/EmailNameParserMatchImpl.java

@@ -7,9 +7,10 @@
 import java.util.List;
 
 /**
+ * Visible only because emailnameparser2 needs to instantiate it. Don't use this, use the interface!
  */
 @Immutable
-final class EmailNameParserMatchImpl implements EmailNameParserMatch {
+public final class EmailNameParserMatchImpl implements EmailNameParserMatch {
 
     @NotNull
     private final List<NameFromEmailAddress> givenNames;
@@ -18,7 +19,7 @@ final class EmailNameParserMatchImpl implements EmailNameParserMatch {
 
     private final double confidence;
 
-    EmailNameParserMatchImpl(@NotNull List<NameFromEmailAddress> givenNames,
+    public EmailNameParserMatchImpl(@NotNull List<NameFromEmailAddress> givenNames,
                              @NotNull List<NameFromEmailAddress> surnames,
                              double confidence) {
         this.givenNames = Collections.unmodifiableList(givenNames);

src/main/java/org/nameapi/client/services/email/emailnameparser/NameFromEmailAddressImpl.java

@@ -5,16 +5,17 @@
 import org.jetbrains.annotations.NotNull;
 
 /**
+ * Visible only because emailnameparser2 needs to instantiate it. Don't use this, use the interface!
  */
 @Immutable
-class NameFromEmailAddressImpl implements NameFromEmailAddress {
+public class NameFromEmailAddressImpl implements NameFromEmailAddress {
 
     @NotNull
     private String name;
     @NotNull
     private EmailAddressNameType nameType;
 
-    NameFromEmailAddressImpl(@NotNull String name, @NotNull EmailAddressNameType nameType) {
+    public NameFromEmailAddressImpl(@NotNull String name, @NotNull EmailAddressNameType nameType) {
         this.name = name;
         this.nameType = nameType;
     }

src/main/java/org/nameapi/client/services/email/emailnameparser2/EmailAddressParsingResultType2.java

@@ -0,0 +1,54 @@
+
+package org.nameapi.client.services.email.emailnameparser2;
+
+/**
+ * Belongs to {@link org.nameapi.client.services.email.emailnameparser2.EmailNameParserResult}, tells what was detected.
+ *
+ * Difference to the EmailAddressParsingResultType:
+ * The enum uses FUNCTIONAL instead of DEPARTMENT and TECHNICAL because the two can hardly be told apart.
+ */
+public enum EmailAddressParsingResultType2 {
+
+    /**
+     * The email address belongs to a department (eg [email protected]) or is
+     * technical (eg [email protected]).
+     */
+    FUNCTIONAL,
+
+    /**
+     * The email address contains a person's initials such as [email protected].
+     * <p>Note that this answer is a guess, the 2 letters could also have another meaning
+     * such as a short given name or surname, or something completely different.</p>
+     */
+    INITIALS,
+
+    /**
+     * The email address contains a person's name such as [email protected].
+     */
+    PERSON_NAME,
+
+    /**
+     * There is no name in the address, for example [email protected]
+     * <p>The address may be personal or non-personal, can't say (as in UNKNOWN)
+     * but it is clear that no name can be found in it.</p>
+     */
+    NOT_A_NAME,
+
+    /**
+     * The email address could not be classified and hence the service failed to extract a name.
+     */
+    UNKNOWN;
+
+    public boolean isUnknown() {
+        return this == UNKNOWN;
+    }
+
+
+    /**
+     * Developer: Call this before doing a switch on an enum value.
+     */
+    public static void assertSize(int size) {
+        assert values().length == size : "Update the code calling this with "+size+"!";
+    }
+
+}

src/main/java/org/nameapi/client/services/email/emailnameparser2/EmailNameParser2Command.java

@@ -0,0 +1,100 @@
+package org.nameapi.client.services.email.emailnameparser2;
+
+import com.google.common.base.Optional;
+import com.optimaize.command4j.ExecutionContext;
+import org.jetbrains.annotations.NotNull;
+import org.nameapi.client.services.NameApiBaseCommand;
+import org.nameapi.client.services.email.emailnameparser.EmailNameParserMatch;
+import org.nameapi.client.services.email.emailnameparser.EmailNameParserMatchImpl;
+import org.nameapi.client.services.email.emailnameparser.NameFromEmailAddress;
+import org.nameapi.client.services.email.emailnameparser.NameFromEmailAddressImpl;
+import org.nameapi.client.services.email.emailnameparser2.wsdl.*;
+
+import java.net.URL;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.Callable;
+
+/**
+ * Analyzes the email address and attempts to extract a person's name.
+ *
+ * <p>Example: [email protected] => [john, doe]</p>
+ *
+ * <p>The service attempts to detect several kinds of syntax, such as:
+ * <ul>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ *     <li>[email protected]</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Names are not formatted to correct case, they are left the way they appeared in the input.</p>
+ *
+ * <p>Difference to the older EmailNameParserCommand:
+ * The enum EmailAddressParsingResultType2 uses FUNCTIONAL instead of DEPARTMENT and TECHNICAL because the two can hardly be told apart.
+ * </p>
+ */
+public class EmailNameParser2Command
+        extends NameApiBaseCommand<SoapEmailNameParser2, String, EmailNameParserResult>
+{
+
+    private static final String servicePath = "/email/emailnameparser2";
+
+    public EmailNameParser2Command() {
+        super(SoapEmailNameParser2.class);
+    }
+
+    @Override @NotNull
+    public EmailNameParserResult call(@NotNull Optional<String> arg, @NotNull ExecutionContext ec) throws Exception {
+        SoapEmailNameParserResult2 soapResult = getPort(ec).parse(getContext(ec), arg.get());
+        return convert(soapResult);
+    }
+
+    @NotNull
+    private EmailNameParserResult convert(@NotNull SoapEmailNameParserResult2 soapResult) {
+        List<EmailNameParserMatch> matches = new ArrayList<>();
+        for (SoapEmailNameParserMatch soapMatch : soapResult.getMatches()) {
+            matches.add( convert(soapMatch) );
+        }
+        return new EmailNameParserResultImpl(soapResult.getResultType(), matches);
+    }
+    @NotNull
+    private EmailNameParserMatch convert(@NotNull SoapEmailNameParserMatch soapMatch) {
+        return new EmailNameParserMatchImpl(
+                convert(soapMatch.getGivenNames()),
+                convert(soapMatch.getSurnames()),
+                soapMatch.getConfidence()
+        );
+    }
+    @NotNull
+    private List<NameFromEmailAddress> convert(@NotNull List<SoapNameFromEmailAddress> list) {
+        List<NameFromEmailAddress> ret = new ArrayList<>();
+        for (SoapNameFromEmailAddress soapName : list) {
+            ret.add(convert(soapName));
+        }
+        return ret;
+    }
+    @NotNull
+    private NameFromEmailAddress convert(@NotNull SoapNameFromEmailAddress soapName) {
+        return new NameFromEmailAddressImpl(soapName.getName(), soapName.getNameType());
+    }
+
+    @NotNull @Override
+    protected Callable<SoapEmailNameParser2> createPort(@NotNull final ExecutionContext ec) {
+        return new Callable<SoapEmailNameParser2>() {
+            @Override
+            public SoapEmailNameParser2 call() throws Exception {
+                URL url = makeUrl(ec, servicePath);
+                return new SoapEmailNameParser2Service(url).getSoapEmailNameParser2Port();
+            }
+        };
+    }
+
+}
+

src/main/java/org/nameapi/client/services/email/emailnameparser2/EmailNameParserResult.java

@@ -0,0 +1,26 @@
+package org.nameapi.client.services.email.emailnameparser2;
+
+import com.google.common.base.Optional;
+import org.jetbrains.annotations.NotNull;
+import org.nameapi.client.services.email.emailnameparser.EmailAddressParsingResultType;
+import org.nameapi.client.services.email.emailnameparser.EmailNameParserMatch;
+
+import java.util.List;
+
+/**
+ */
+public interface EmailNameParserResult {
+
+    @NotNull
+    EmailAddressParsingResultType2 getResultType();
+
+    @NotNull
+    Optional<EmailNameParserMatch> getBestNameMatch();
+
+    /**
+     * The first entry (if any) is the best, they are ordered by likeliness in descending order.
+     */
+    @NotNull
+    List<EmailNameParserMatch> getNameMatches();
+
+}

src/main/java/org/nameapi/client/services/email/emailnameparser2/EmailNameParserResultImpl.java

@@ -0,0 +1,49 @@
+package org.nameapi.client.services.email.emailnameparser2;
+
+import com.google.common.base.Optional;
+import crema.annotation.Immutable;
+import org.jetbrains.annotations.NotNull;
+import org.nameapi.client.services.email.emailnameparser.EmailAddressParsingResultType;
+import org.nameapi.client.services.email.emailnameparser.EmailNameParserMatch;
+
+import java.util.Collections;
+import java.util.List;
+
+/**
+ */
+@Immutable
+class EmailNameParserResultImpl implements EmailNameParserResult {
+
+    @NotNull
+    private final EmailAddressParsingResultType2 resultType;
+    @NotNull
+    private final List<EmailNameParserMatch> matches;
+
+    EmailNameParserResultImpl(@NotNull EmailAddressParsingResultType2 resultType, @NotNull List<EmailNameParserMatch> matches) {
+        this.resultType = resultType;
+        this.matches    = Collections.unmodifiableList(matches);
+    }
+
+
+    @Override @NotNull
+    public EmailAddressParsingResultType2 getResultType() {
+        return resultType;
+    }
+
+    @NotNull @Override
+    public Optional<EmailNameParserMatch> getBestNameMatch() {
+        if (matches.isEmpty()) return Optional.absent();
+        return Optional.of(matches.get(0));
+    }
+
+    @NotNull @Override
+    public List<EmailNameParserMatch> getNameMatches() {
+        return matches;
+    }
+
+    @Override @NotNull
+    public String toString() {
+        return getResultType() + ": "+matches;
+    }
+
+}