Javadoc fixes and pom config for source and javadoc jars

Author: arjantijms

soteria-edr1/pom.xml

@@ -37,6 +37,46 @@
 					<target>1.8</target>
 				</configuration>
 			</plugin>
+            
+            <!-- Configure the jar with the sources (or rather, convince Maven that we want sources at all) -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>2.4</version>
+                <executions>
+                    <execution>
+                        <id>attach-sources</id>
+                        <goals>
+                            <goal>jar-no-fork</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            
+            <!-- Configure the jar with the javadoc (or rather, convince Maven that we want javadoc at all) -->
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-javadoc-plugin</artifactId>
+                <version>2.10.3</version>
+                <configuration>
+                    <javadocVersion>1.8</javadocVersion>
+                    <notimestamp>true</notimestamp>
+                    <splitindex>true</splitindex>
+                    <doctitle>Soteria API documentation</doctitle>
+                    <links>
+                        <link>https://docs.oracle.com/javaee/7/api/</link>
+                    </links>
+                </configuration>
+                <executions>
+                    <execution>
+                        <id>attach-javadocs</id>
+                        <goals>
+                            <goal>jar</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+            
 		</plugins>
 	</build>
 </project>

soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/HttpAuthenticationMechanism.java

@@ -87,7 +87,7 @@ public interface HttpAuthenticationMechanism {
      * <p>
      * This method is called in response to an HTTP client request for a resource, and is always invoked 
      * <strong>before</strong> any {@link Filter} or {@link HttpServlet}. Additionally this method is called
-     * in response to {@link HttpServletRequest#authenticate(HttpServletResponse).}
+     * in response to {@link HttpServletRequest#authenticate(HttpServletResponse)}
      * 
      * <p>
      * Note that by default this method is <strong>always</strong> called for every request, independent of whether

soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/HttpMessageContext.java

@@ -64,7 +64,7 @@ public interface HttpMessageContext {
     /**
      * Checks if the current request is to a protected resource or not. A protected resource
      * is a resource (e.g. a Servlet, JSF page, JSP page etc) for which a constraint has been defined
-     * in e.g. <code>web.xml<code>.
+     * in e.g. <code>web.xml</code>.
      * 
      * @return true if a protected resource was requested, false if a public resource was requested.
      */
@@ -118,6 +118,8 @@ public interface HttpMessageContext {
     /**
      * Returns the named module option that was set on the auth module to which this context belongs.
      * 
+     * @param key name of the module option
+     * 
      * @return the named module option that was set on the auth module to which this context belongs, or null if no option with that name was set.
      */
     String getModuleOption(String key);

soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/annotation/AutoApplySession.java

@@ -51,11 +51,11 @@
 
 /**
  * The AutoApplySession annotation provides an application the ability to declarative designate 
- * that an {@link AuthenticationMechanism} uses the <code>javax.servlet.http.registerSession<code> 
+ * that an {@link AuthenticationMechanism} uses the <code>javax.servlet.http.registerSession</code> 
  * and auto applies this for every request.
  * 
  * <p>
- * See the JASPIC specification for further details on <code>javax.servlet.http.registerSession<code>.
+ * See the JASPIC specification for further details on <code>javax.servlet.http.registerSession</code>.
  * 
  * <p>
  * This support is provided via an implementation of an interceptor spec interceptor that conducts the

soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/annotation/BasicAuthenticationMechanismDefinition.java

@@ -65,6 +65,8 @@
      * Note that contrary to what happens in some proprietary Servlet products, this
      * realm name <b>does not</b> couple a named identity store configuration to the 
      * authentication mechanism.  
+     * 
+     * @return Name of realm
      */
     String realmName() default "";
 }

soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/annotation/RememberMe.java

@@ -102,6 +102,8 @@
      * 
      * @see Cookie#setMaxAge(int)
      * 
+     * @return Max age in seconds
+     * 
      */
     @Nonbinding
     int cookieMaxAgeSeconds() default 86400; // 1 day
@@ -113,6 +115,8 @@
      * as well as default classes as specified by EL 3.0 for the {@link ELProcessor}
      * and the implicit object "this" which refers to the interceptor target.
      * 
+     * @return EL expression to determine if remember me should be used
+     * 
      */
     @Nonbinding
     String isRememberMeExpression() default "";

soteria-edr1/src/main/java/javax/security/identitystore/CredentialValidationResult.java

@@ -88,7 +88,7 @@ public enum Status {
 	 *
 	 * @param status
 	 *            Validation status
-	 * @param callerName
+	 * @param callerPrincipal
 	 *            Validated caller
 	 * @param groups
 	 *            Groups associated with the caller from the identity store

soteria-edr1/src/main/java/javax/security/identitystore/annotation/Credentials.java

@@ -59,16 +59,22 @@
 
     /**
      * Name of caller. This is the name a caller uses to authenticate with.
+     * 
+     * @return Name of caller
      */
     String callerName();
 
     /**
      * A text-based password used by the caller to authenticate.
+     * 
+     * @return A text-based password
      */
     String password();
 
     /**
      * The optional list of groups that the specified caller is in.
+     * 
+     * @return optional list of groups
      */
     String[] groups() default {};
 }

soteria-edr1/src/main/java/javax/security/identitystore/annotation/DataBaseIdentityStoreDefinition.java

@@ -62,6 +62,8 @@
     /**
      * Full JNDI name of the data source that provides access to the data base where the 
      * caller identities are stored. 
+     * 
+     * @return Full JNDI name of the data source
      */
 	String dataSourceLookup() default "java:comp/DefaultDataSource"; // default data source
 
@@ -78,7 +80,9 @@
 	 * <code>
 	 * select password from caller where name = ?
 	 * </code>
-	 * <pre>
+	 * </pre>
+	 * 
+	 * @return SQL query to validate
 	 */
 	String callerQuery();
 
@@ -95,18 +99,24 @@
      * <code>
      * select group_name from caller_groups where caller_name = ?
      * </code>
-     * <pre>
+     * </pre>
+     * 
+     * @return SQL query to retrieve the groups
      */
 	String groupsQuery();
 
 	/**
 	 * Hash algorithm applied to plain text password for comparison with password
 	 * returned from {@link #groupsQuery()}.
+	 * 
+	 * @return Hash algorithm applied to plain text password
 	 */
 	String hashAlgorithm() default ""; // default no hash (for now) todo: make enum?
 
 	/**
 	 * Encoding used for hash. TODO
+	 * 
+	 *  @return Encoding used for hash
 	 */
 	String hashEncoding() default ""; // default no encoding (for now) todo: make enum?
 

soteria-edr1/src/main/java/javax/security/identitystore/annotation/EmbeddedIdentityStoreDefinition.java

@@ -65,8 +65,8 @@
  *  {@literal @}Credentials(callerName = "peter", password = "secret1", groups = { "foo", "bar" }),
  *  {@literal @}Credentials(callerName = "john", password = "secret2", groups = { "foo", "kaz" }),
  *  {@literal @}Credentials(callerName = "carla", password = "secret3", groups = { "foo" }) })
- * <code>
- * <pre>
+ * </code>
+ * </pre>
  * 
  * @author Arjan Tijms
  *
@@ -79,6 +79,8 @@
 
     /**
      * Defines the caller identities stored in the embedded identity store
+     * 
+     * @return caller identities stored in the embedded identity store
      */
     Credentials[] value() default {};
 

soteria-edr1/src/main/java/javax/security/identitystore/annotation/LdapIdentityStoreDefinition.java

@@ -62,12 +62,16 @@
     /**
      * URL where the LDAP server can be reached.
      * E.g. <code>ldap://localhost:33389"</code>
+     * 
+     * @return URL where the LDAP server can be reached
      */
     String url() default "";
 
     /**
      * Base of the distinguished name that contains the caller name.
      * E.g. <code>ou=caller,dc=jsr375,dc=net</code>
+     * 
+     * @return Base of the distinguished name that contains the caller name
      */
     String callerBaseDn() default "";
 
@@ -98,13 +102,17 @@
      * sn: Peter
      * userPassword: secret1
      * </code>
-     * <pre>
+     * </pre>
+     * 
+     * @return Name of the attribute that contains the caller name
      */
     String callerNameAttribute() default "uid";
 
     /**
      * Base of the distinguished name that contains the groups
      * E.g. <code>ou=group,dc=jsr375,dc=net</code>
+     * 
+     * @return Base of the distinguished name that contains the groups
      */
 	String groupBaseDn() default "";
 
@@ -121,6 +129,8 @@
      * <li> {@link #groupBaseDn()} corresponds to <code>ou=group,dc=jsr375,dc=net</code> </li>
      * <li> <code>foo</code> is the group name that will be returned by the store when authentication succeeds</li>
      * </ul>
+     * 
+     * @return Name of the attribute that contains the group name
 	 */
 	String groupNameAttribute() default "cn";
 
@@ -139,7 +149,9 @@
      * member: uid=pete,ou=caller,dc=jsr375,dc=net
      * member: uid=john,ou=caller,dc=jsr375,dc=net 
      * </code>
-     * <pre>
+     * </pre>
+     * 
+     * @return DN attribute for the group DN
 	 */
 	String groupCallerDnAttribute() default "member";
 

soteria-edr1/src/main/java/javax/security/identitystore/credential/RememberMeCredential.java

@@ -42,7 +42,6 @@
 /**
  * <code>RememberMeCredential</code> represents a credential presented as a token,
  * for the explicit usage with the JSR 375 provided remember me function.
- * <p>
  *
  */
 public class RememberMeCredential implements Credential {
@@ -52,7 +51,6 @@ public class RememberMeCredential implements Credential {
     /**
      * Constructor
      *
-     * @param caller The caller associated with this credential
      * @param token  The token value to compare for authentication.
      */
     public RememberMeCredential(String token) {

soteria-edr1/src/main/java/javax/security/identitystore/credential/TokenCredential.java

@@ -42,7 +42,6 @@
 /**
  * <code>TokenCredential</code> represents a credential presented as a token,
  * such as a JWT or a proprietary token value.
- * <p>
  *
  */
 public class TokenCredential implements Credential {

soteria-edr1/src/main/java/org/glassfish/soteria/mechanisms/jaspic/DefaultAuthConfigProvider.java

@@ -31,8 +31,8 @@ public DefaultAuthConfigProvider(ServerAuthModule serverAuthModule) {
     /**
      * Constructor with signature and implementation that's required by API.
      * 
-     * @param properties
-     * @param factory
+     * @param properties provider properties
+     * @param factory the auth config factory
      */
     public DefaultAuthConfigProvider(Map<String, String> properties, AuthConfigFactory factory) {
         this.providerProperties = properties;

soteria-edr1/src/main/java/org/glassfish/soteria/mechanisms/jaspic/Jaspic.java

@@ -233,6 +233,8 @@ public static AuthStatus getLastStatus(HttpServletRequest request) {
 	 * user is going to be authenticated (as opposed to using the handler for the "do nothing" protocol
 	 * which uses the unauthenticated identity).
 	 * 
+	 * @param request The involved HTTP servlet request.
+	 * 
 	 */
 	public static void setDidAuthentication(HttpServletRequest request) {
 		request.setAttribute(DID_AUTHENTICATION, TRUE);
@@ -243,6 +245,11 @@ public static void setDidAuthentication(HttpServletRequest request) {
 	 * the current request.
 	 * Does not necessarily mean that authentication has indeed succeeded, for this
 	 * the actual user/caller principal should be checked as well.
+	 * 
+	 * @param request The involved HTTP servlet request.
+	 * 
+	 * @return true if a SAM has indicated that it intended authentication to be happening during
+     * the current request.
 	 * 
 	 */
 	public static boolean isDidAuthentication(HttpServletRequest request) {