From da3801b9147207651784d5b7650fd9cb7c61af19 Mon Sep 17 00:00:00 2001
From: Luke Taylor <luke.taylor@springsource.com>
Date: Wed, 9 Mar 2005 02:02:05 +0000
Subject: [PATCH] Javadoc improvements.

---
 .../x509/X509AuthoritiesPopulator.java        | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 core/src/main/java/org/acegisecurity/providers/x509/X509AuthoritiesPopulator.java

diff --git a/core/src/main/java/org/acegisecurity/providers/x509/X509AuthoritiesPopulator.java b/core/src/main/java/org/acegisecurity/providers/x509/X509AuthoritiesPopulator.java
new file mode 100644
index 0000000000..271d2707b7
--- /dev/null
+++ b/core/src/main/java/org/acegisecurity/providers/x509/X509AuthoritiesPopulator.java
@@ -0,0 +1,40 @@
+package net.sf.acegisecurity.providers.x509;
+
+import net.sf.acegisecurity.UserDetails;
+import net.sf.acegisecurity.AuthenticationException;
+
+import java.security.cert.X509Certificate;
+
+/**
+ * Populates the <code>UserDetails</code> associated with the X.509
+ * certificate presented by a client.
+ * <p>
+ * Although the certificate will already have been validated by the web container,
+ * implementations may choose to perform additional application-specific checks on
+ * the certificate content here. If an implementation chooses to reject the certificate,
+ * it should throw a {@link net.sf.acegisecurity.BadCredentialsException}.
+ * </p>
+ *
+ * @author Luke
+ */
+public interface X509AuthoritiesPopulator {
+    /**
+     * Obtains the granted authorities for the specified user.
+     *
+     * <p>
+     * May throw any <code>AuthenticationException</code> or return
+     * <code>null</code> if the authorities are unavailable.
+     * </p>
+     *
+     * @param userCertificate the X.509 certificate supplied
+     *
+     * @return the details of the indicated user (at minimum the granted
+     *         authorities and the username)
+     *
+     * @throws net.sf.acegisecurity.AuthenticationException if the user details are not available
+     *  or the certificate isn't valid for the application's purpose.
+     */
+    public UserDetails getUserDetails(X509Certificate userCertificate)
+        throws AuthenticationException;
+
+}