Javadoc fixes and pom config for source and javadoc jars

arjantijms · arjantijms · commit ce6e34e57e26 · 2016-01-30T23:40:44.000+01:00
diff --git a/soteria-edr1/pom.xml b/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>
diff --git a/soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/HttpAuthenticationMechanism.java b/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
diff --git a/soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/HttpMessageContext.java b/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);
diff --git a/soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/annotation/AutoApplySession.java b/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
diff --git a/soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/annotation/BasicAuthenticationMechanismDefinition.java b/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 "";
 }
diff --git a/soteria-edr1/src/main/java/javax/security/authentication/mechanism/http/annotation/RememberMe.java b/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 "";
diff --git a/soteria-edr1/src/main/java/javax/security/identitystore/CredentialValidationResult.java b/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
diff --git a/soteria-edr1/src/main/java/javax/security/identitystore/annotation/Credentials.java b/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 {};
 }
diff --git a/soteria-edr1/src/main/java/javax/security/identitystore/annotation/DataBaseIdentityStoreDefinition.java b/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?
 
diff --git a/soteria-edr1/src/main/java/javax/security/identitystore/annotation/EmbeddedIdentityStoreDefinition.java b/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 {};
 
diff --git a/soteria-edr1/src/main/java/javax/security/identitystore/annotation/LdapIdentityStoreDefinition.java b/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";
 
diff --git a/soteria-edr1/src/main/java/javax/security/identitystore/credential/RememberMeCredential.java b/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) {
diff --git a/soteria-edr1/src/main/java/javax/security/identitystore/credential/TokenCredential.java b/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 {
diff --git a/soteria-edr1/src/main/java/org/glassfish/soteria/mechanisms/jaspic/DefaultAuthConfigProvider.java b/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;
diff --git a/soteria-edr1/src/main/java/org/glassfish/soteria/mechanisms/jaspic/Jaspic.java b/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) {

Original file line number	Diff line number	Diff line change
`@@ -87,7 +87,7 @@ public interface HttpAuthenticationMechanism {`
`87`	`87`	`* <p>`
`88`	`88`	`* This method is called in response to an HTTP client request for a resource, and is always invoked`
`89`	`89`	`* <strong>before</strong> any {@link Filter} or {@link HttpServlet}. Additionally this method is called`
`90`		`- * in response to {@link HttpServletRequest#authenticate(HttpServletResponse).}`
	`90`	`+ * in response to {@link HttpServletRequest#authenticate(HttpServletResponse)}`
`91`	`91`	`*`
`92`	`92`	`* <p>`
`93`	`93`	`* Note that by default this method is <strong>always</strong> called for every request, independent of whether`
Original file line number	Diff line number	Diff line change
`@@ -51,11 +51,11 @@`
`51`	`51`
`52`	`52`	`/**`
`53`	`53`	`* The AutoApplySession annotation provides an application the ability to declarative designate`
`54`		`- * that an {@link AuthenticationMechanism} uses the <code>javax.servlet.http.registerSession<code>`
	`54`	`+ * that an {@link AuthenticationMechanism} uses the <code>javax.servlet.http.registerSession</code>`
`55`	`55`	`* and auto applies this for every request.`
`56`	`56`	`*`
`57`	`57`	`* <p>`
`58`		`- * See the JASPIC specification for further details on <code>javax.servlet.http.registerSession<code>.`
	`58`	`+ * See the JASPIC specification for further details on <code>javax.servlet.http.registerSession</code>.`
`59`	`59`	`*`
`60`	`60`	`* <p>`
`61`	`61`	`* This support is provided via an implementation of an interceptor spec interceptor that conducts the`
Original file line number	Diff line number	Diff line change
`@@ -65,6 +65,8 @@`
`65`	`65`	`* Note that contrary to what happens in some proprietary Servlet products, this`
`66`	`66`	`* realm name <b>does not</b> couple a named identity store configuration to the`
`67`	`67`	`* authentication mechanism.`
	`68`	`+ *`
	`69`	`+ * @return Name of realm`
`68`	`70`	`*/`
`69`	`71`	`String realmName() default "";`
`70`	`72`	`}`
Original file line number	Diff line number	Diff line change
`@@ -102,6 +102,8 @@`
`102`	`102`	`*`
`103`	`103`	`* @see Cookie#setMaxAge(int)`
`104`	`104`	`*`
	`105`	`+ * @return Max age in seconds`
	`106`	`+ *`
`105`	`107`	`*/`
`106`	`108`	`@Nonbinding`
`107`	`109`	`int cookieMaxAgeSeconds() default 86400; // 1 day`
`@@ -113,6 +115,8 @@`
`113`	`115`	`* as well as default classes as specified by EL 3.0 for the {@link ELProcessor}`
`114`	`116`	`* and the implicit object "this" which refers to the interceptor target.`
`115`	`117`	`*`
	`118`	`+ * @return EL expression to determine if remember me should be used`
	`119`	`+ *`
`116`	`120`	`*/`
`117`	`121`	`@Nonbinding`
`118`	`122`	`String isRememberMeExpression() default "";`
Original file line number	Diff line number	Diff line change
`@@ -88,7 +88,7 @@ public enum Status {`
`88`	`88`	`*`
`89`	`89`	`* @param status`
`90`	`90`	`* Validation status`
`91`		`- * @param callerName`
	`91`	`+ * @param callerPrincipal`
`92`	`92`	`* Validated caller`
`93`	`93`	`* @param groups`
`94`	`94`	`* Groups associated with the caller from the identity store`