JavaDoc updates
git-svn-id: https://svn.apache.org/repos/asf/incubator/jsecurity/trunk@711122 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/org/jsecurity/authc/Account.java b/src/org/jsecurity/authc/Account.java
index f80e10d..77dd477 100644
--- a/src/org/jsecurity/authc/Account.java
+++ b/src/org/jsecurity/authc/Account.java
@@ -22,8 +22,11 @@
/**
* An <tt>Account</tt> is a convenience interface that extends both {@link AuthenticationInfo} and
- * {@link AuthorizationInfo}. This interface can be useful when an application uses a single object to
- * encapsulate both the authentication and authorization information required by a {@link org.jsecurity.realm.Realm Realm}.
+ * {@link AuthorizationInfo} and represents authentication and authorization for a <em>single account</em> in a
+ * <em>single Realm</em>.
+ * <p/>
+ * This interface can be useful when an Realm implementation finds it more convenient to use a single object to
+ * encapsulate both the authentication and authorization information used by both authc and authz operations.
* <p/>
* <b>Please Note</b>: Since JSecurity sometimes logs account operations, please ensure your Account's <code>toString()</code>
* implementation does <em>not</em> print out account credentials (password, etc), as these might be viewable to
diff --git a/src/org/jsecurity/authc/AuthenticationInfo.java b/src/org/jsecurity/authc/AuthenticationInfo.java
index 56f4eec..eacc7d6 100644
--- a/src/org/jsecurity/authc/AuthenticationInfo.java
+++ b/src/org/jsecurity/authc/AuthenticationInfo.java
@@ -63,7 +63,7 @@
* to the application to identify the current <code>Subject</code>.
* <p/>
* At least one of these attributes should be the account's 'primary' identifier, such as a username or unique
- * user id. By convention, usually the first principal (that is, <code>principals.iterator().next()</code>) is the
+ * user id. By convention, usually the first principal (that is, <code>getPrincipals().iterator().next()</code>) is the
* 'primary' one.
* <p/>
* The returned PrincipalCollection should <em>not</em> contain any credentials used to verify principals, such
@@ -75,7 +75,9 @@
/**
* Returns the credentials associated with the corresponding Subject. A credential verifies one or more of the
- * {@link #getPrincipals() principals} associated with the Subject, such as a password or private key.
+ * {@link #getPrincipals() principals} associated with the Subject, such as a password or private key. Credentials
+ * are used by JSecurity particularly during the authentication process to ensure that submitted credentials
+ * during a login attempt match exactly the credentials here in the <code>AuthenticationInfo</code> instance.
*
* @return the credentials associated with the corresponding Subject.
*/
diff --git a/src/org/jsecurity/authc/SimpleAuthenticationInfo.java b/src/org/jsecurity/authc/SimpleAuthenticationInfo.java
index e5adfac..9106ab7 100644
--- a/src/org/jsecurity/authc/SimpleAuthenticationInfo.java
+++ b/src/org/jsecurity/authc/SimpleAuthenticationInfo.java
@@ -27,37 +27,68 @@
import java.util.Set;
/**
- * Simple value object implementation of the {@link MergableAuthenticationInfo} interface that holds the principals and
+ * Simple implementation of the {@link MergableAuthenticationInfo} interface that holds the principals and
* credentials.
*
- * TODO - JavaDoc remaining methods.
- *
- * @author Jeremy Haile
* @see org.jsecurity.realm.AuthenticatingRealm
* @since 0.9
+ * @author Jeremy Haile
+ * @author Les Hazlewood
*/
public class SimpleAuthenticationInfo implements MergableAuthenticationInfo {
+ /**
+ * The principals identifying the account associated with this AuthenticationInfo instance.
+ */
protected PrincipalCollection principals;
+ /**
+ * The credentials verifying the account principals.
+ */
protected Object credentials;
+ /**
+ * Default no-argument constructor.
+ */
public SimpleAuthenticationInfo() {
}
+ /**
+ * Constructor that takes in a single 'primary' principal of the account and its corresponding credentials,
+ * associated with the specified realm.
+ * <p/>
+ * This is a convenience constructor and will construct a {@link PrincipalCollection PrincipalCollection} based
+ * on the <code>principal</code> and <code>realmName</code> argument.
+ *
+ * @param principal the 'primary' principal associated with the specified realm.
+ * @param credentials the credentials that verify the given principal.
+ * @param realmName the realm from where the principal and credentials were acquired.
+ */
public SimpleAuthenticationInfo(Object principal, Object credentials, String realmName) {
this.principals = new SimplePrincipalCollection(principal, realmName);
this.credentials = credentials;
}
+ /**
+ * Constructor that takes in an account's identifying principal(s) and its corresponding credentials that verify
+ * the principals.
+ * @param principals a Realm's account's identifying principal(s)
+ * @param credentials the accounts corresponding principals that verify the principals.
+ */
public SimpleAuthenticationInfo(PrincipalCollection principals, Object credentials) {
this.principals = new SimplePrincipalCollection(principals);
this.credentials = credentials;
}
+
public PrincipalCollection getPrincipals() {
return principals;
}
+ /**
+ * Sets the identifying principal(s) represented by this instance.
+ *
+ * @param principals the indentifying attributes of the corresponding Realm account.
+ */
public void setPrincipals(PrincipalCollection principals) {
this.principals = principals;
}
@@ -66,10 +97,18 @@
return credentials;
}
+ /**
+ * Sets the credentials that verify the principals/identity of the associated Realm account.
+ * @param credentials attribute(s) that verify the account's identity/principals, such as a password or private key.
+ */
public void setCredentials(Object credentials) {
this.credentials = credentials;
}
+ /**
+ * Takes the specified <code>info</code> argument and adds its principals and credentials into this instance.
+ * @param info the <code>AuthenticationInfo</code> to add into this instance.
+ */
@SuppressWarnings("unchecked")
public void merge(AuthenticationInfo info) {
if (info == null || info.getPrincipals() == null || info.getPrincipals().isEmpty()) {
@@ -113,6 +152,13 @@
}
}
+ /**
+ * Returns <code>true</code> if the Object argument is an <code>instanceof SimpleAuthenticationInfo</code> and
+ * its {@link #getPrincipals() principals} are equal to this instance's principals, <code>false</code> otherwise.
+ * @param o the object to compare for equality.
+ * @return <code>true</code> if the Object argument is an <code>instanceof SimpleAuthenticationInfo</code> and
+ * its {@link #getPrincipals() principals} are equal to this instance's principals, <code>false</code> otherwise.
+ */
public boolean equals(Object o) {
if (this == o) return true;
if (!(o instanceof SimpleAuthenticationInfo)) return false;
@@ -124,10 +170,18 @@
return true;
}
+ /**
+ * Returns the hashcode of the internal {@link #getPrincipals() principals} instance.
+ * @return the hashcode of the internal {@link #getPrincipals() principals} instance.
+ */
public int hashCode() {
return (principals != null ? principals.hashCode() : 0);
}
+ /**
+ * Simple implementation that merely returns <code>{@link #getPrincipals() principals}.toString()</code>
+ * @return <code>{@link #getPrincipals() principals}.toString()</code>
+ */
public String toString() {
return principals.toString();
}
diff --git a/src/org/jsecurity/authz/SimpleAuthorizationInfo.java b/src/org/jsecurity/authz/SimpleAuthorizationInfo.java
index 6b59832..27e4555 100644
--- a/src/org/jsecurity/authz/SimpleAuthorizationInfo.java
+++ b/src/org/jsecurity/authz/SimpleAuthorizationInfo.java
@@ -23,26 +23,41 @@
import java.util.Set;
/**
- * Simple value object implementation of the {@link AuthorizationInfo} interface that stores roles and permissions.
+ * Simple POJO implementation of the {@link AuthorizationInfo} interface that stores roles and permissions as internal
+ * attributes.
*
- * @author Jeremy Haile
- * @author Les Hazlewood
* @see org.jsecurity.realm.AuthorizingRealm
* @since 0.9
+ * @author Jeremy Haile
+ * @author Les Hazlewood
*/
public class SimpleAuthorizationInfo implements AuthorizationInfo {
- //TODO - JavaDoc
-
+ /**
+ * The internal roles collection.
+ */
protected Set<String> roles;
+ /**
+ * Collection of all string-based permissions associated with the account.
+ */
protected Set<String> stringPermissions;
+ /**
+ * Collection of all object-based permissions associaed with the account.
+ */
protected Set<Permission> objectPermissions;
+ /**
+ * Default no-argument constructor.
+ */
public SimpleAuthorizationInfo() {
}
+ /**
+ * Creates a new instance with the specified roles and no permissions.
+ * @param roles the roles assigned to the realm account.
+ */
public SimpleAuthorizationInfo(Set<String> roles) {
this.roles = roles;
}
@@ -51,10 +66,19 @@
return roles;
}
+ /**
+ * Sets the roles assigned to the account.
+ * @param roles the roles assigned to the account.
+ */
public void setRoles(Set<String> roles) {
this.roles = roles;
}
+ /**
+ * Adds (assigns) a role to those associated with the account. If the account doesn't yet have any roles, a
+ * new roles collection (a Set) will be created automatically.
+ * @param role the role to add to those associated with the account.
+ */
public void addRole(String role) {
if (this.roles == null) {
this.roles = new HashSet<String>();
@@ -62,6 +86,11 @@
this.roles.add(role);
}
+ /**
+ * Adds (assigns) multiple roles to those associated with the account. If the account doesn't yet have any roles, a
+ * new roles collection (a Set) will be created automatically.
+ * @param roles the roles to add to those associated with the account.
+ */
public void addRoles(Collection<String> roles) {
if (this.roles == null) {
this.roles = new HashSet<String>();
@@ -73,10 +102,22 @@
return stringPermissions;
}
+ /**
+ * Sets the string-based permissions assigned directly to the account. The permissions set here, in addition to any
+ * {@link #getObjectPermissions() object permissions} constitute the total permissions assigned directly to the
+ * account.
+ *
+ * @param stringPermissions the string-based permissions assigned directly to the account.
+ */
public void setStringPermissions(Set<String> stringPermissions) {
this.stringPermissions = stringPermissions;
}
+ /**
+ * Adds (assigns) a permission to those directly associated with the account. If the account doesn't yet have any
+ * direct permissions, a new permission collection (a Set<String>) will be created automatically.
+ * @param permission the permission to add to those directly assigned to the account.
+ */
public void addStringPermission(String permission) {
if (this.stringPermissions == null) {
this.stringPermissions = new HashSet<String>();
@@ -84,7 +125,11 @@
this.stringPermissions.add(permission);
}
-
+ /**
+ * Adds (assigns) multiple permissions to those associated directly with the account. If the account doesn't yet
+ * have any string-based permissions, a new permissions collection (a Set<String>) will be created automatically.
+ * @param permissions the permissions to add to those associated directly with the account.
+ */
public void addStringPermissions(Collection<String> permissions) {
if (this.stringPermissions == null) {
this.stringPermissions = new HashSet<String>();
@@ -96,10 +141,22 @@
return objectPermissions;
}
+ /**
+ * Sets the object-based permissions assigned directly to the account. The permissions set here, in addition to any
+ * {@link #getStringPermissions() string permissions} constitute the total permissions assigned directly to the
+ * account.
+ *
+ * @param objectPermissions the object-based permissions assigned directly to the account.
+ */
public void setObjectPermissions(Set<Permission> objectPermissions) {
this.objectPermissions = objectPermissions;
}
+ /**
+ * Adds (assigns) a permission to those directly associated with the account. If the account doesn't yet have any
+ * direct permissions, a new permission collection (a Set<{@link Permission Permission}>) will be created automatically.
+ * @param permission the permission to add to those directly assigned to the account.
+ */
public void addObjectPermission(Permission permission) {
if (this.objectPermissions == null) {
this.objectPermissions = new HashSet<Permission>();
@@ -107,6 +164,12 @@
this.objectPermissions.add(permission);
}
+ /**
+ * Adds (assigns) multiple permissions to those associated directly with the account. If the account doesn't yet
+ * have any object-based permissions, a new permissions collection (a Set<{@link Permission Permission}>)
+ * will be created automatically.
+ * @param permissions the permissions to add to those associated directly with the account.
+ */
public void addObjectPermissions(Collection<Permission> permissions) {
if (this.objectPermissions == null) {
this.objectPermissions = new HashSet<Permission>();
diff --git a/src/org/jsecurity/crypto/BlowfishCipher.java b/src/org/jsecurity/crypto/BlowfishCipher.java
index a0f4928..38fa956 100644
--- a/src/org/jsecurity/crypto/BlowfishCipher.java
+++ b/src/org/jsecurity/crypto/BlowfishCipher.java
@@ -55,10 +55,14 @@
*/
public class BlowfishCipher implements Cipher {
- //TODO - complete JavaDoc
-
+ /**
+ * The JDK Crypto Cipher algorithm to use for this class, equal to "Blowfish".
+ */
private static final String ALGORITHM = "Blowfish";
+ /**
+ * The JDK Crypto Transformation string to use for this class, equal to {@link #ALGORITHM ALGORITHM} + "/ECB/PKCS5Padding";
+ */
private static final String TRANSFORMATION_STRING = ALGORITHM + "/ECB/PKCS5Padding";
//The following KEY_BYTES String was created by running
@@ -68,21 +72,52 @@
private static final byte[] KEY_BYTES = Base64.decode("jJ9Kg1BAevbvhSg3vBfwfQ==");
private static final Key DEFAULT_CIPHER_KEY = new SecretKeySpec(KEY_BYTES, ALGORITHM);
+ /**
+ * Internal private log instance.
+ */
private static final Log log = LogFactory.getLog(BlowfishCipher.class);
+ /**
+ * The key to use by default, can be overridden by calling {@link #setKey(java.security.Key)}.
+ */
private Key key = DEFAULT_CIPHER_KEY;
+ /**
+ * Default no argument constructor that uses an internal default {@link #getKey() key} to use during
+ * encryption and decryption. For propery security, you should definitely supply your own key by using the
+ * {@link #setKey(java.security.Key) setKey(Key)} method.
+ */
public BlowfishCipher() {
}
+ /**
+ * Returns the default {@link Key Key} to use for symmetric encryption and decryption if one is not specified during
+ * encryption/decryption. For truly secure applications,
+ * you should always specify your own key via the {@link #setKey(java.security.Key) setKey} method.
+ * @return the {@link Key Key} to use for symmetric encryption and decryption.
+ * @see #encrypt(byte[], byte[])
+ * @see #decrypt(byte[], byte[])
+ */
public Key getKey() {
return key;
}
+ /**
+ * Sets the internal default {@link Key Key} to use for symmetric encryption and decryption if one is not
+ * specified during encryption/decryption. For truly secure applications, you should always specify your own
+ * key via this method.
+ * @param key the key to use for symmetric encryption and decryption.
+ * @see #encrypt(byte[], byte[])
+ * @see #decrypt(byte[], byte[])
+ */
public void setKey(Key key) {
this.key = key;
}
+ /**
+ * Encrypts the specified raw byte array. If the <code>key</code> argument is null, the internal default
+ * {@link #getKey() key} will be used to encrypt the byte array.
+ */
public byte[] encrypt(byte[] raw, byte[] key) {
byte[] encrypted = crypt(raw, javax.crypto.Cipher.ENCRYPT_MODE, key);
if (log.isTraceEnabled()) {
@@ -92,6 +127,10 @@
return encrypted;
}
+ /**
+ * Decrypts the specified already-encrypted byte array. If the <code>key</code> argument is null, the internal default
+ * {@link #getKey() key} will be used to encrypt the byte array.
+ */
public byte[] decrypt(byte[] encrypted, byte[] key) {
if (log.isTraceEnabled()) {
log.trace("Attempting to decrypt incoming byte array of length " +
@@ -100,7 +139,14 @@
return crypt(encrypted, javax.crypto.Cipher.DECRYPT_MODE, key);
}
- protected javax.crypto.Cipher newCipherInstance() {
+ /**
+ * Returns a new {@link javax.crypto.Cipher Cipher} instance to use for encryption/decryption operations, based on
+ * the {@link #TRANSFORMATION_STRING TRANSFORMATION_STRING} constant.
+ * @return a new Cipher instance.
+ * @throws IllegalStateException if a new Cipher instance cannot be constructed based on the
+ * {@link #TRANSFORMATION_STRING TRANSFORMATION_STRING} constant.
+ */
+ protected javax.crypto.Cipher newCipherInstance() throws IllegalStateException {
try {
return javax.crypto.Cipher.getInstance(TRANSFORMATION_STRING);
} catch (Exception e) {
@@ -112,6 +158,14 @@
}
}
+ /**
+ * Initializes the JDK Cipher with the specified mode and key. This is primarily a utility method to catch any
+ * potential {@link InvalidKeyException InvalidKeyException} that might arise.
+ *
+ * @param cipher the JDK Cipher to {@link javax.crypto.Cipher#init(int, java.security.Key) init}.
+ * @param mode the Cipher mode
+ * @param key the Cipher's Key
+ */
protected void init(javax.crypto.Cipher cipher, int mode, java.security.Key key) {
try {
cipher.init(mode, key);
@@ -121,6 +175,13 @@
}
}
+ /**
+ * Calls the {@link javax.crypto.Cipher#doFinal(byte[]) doFinal(bytes)} method, propagating any exception that
+ * might arise in an {@link IllegalStateException IllegalStateException}
+ * @param cipher the JDK Cipher to finalize (perform the actual cryption)
+ * @param bytes the bytes to crypt
+ * @return the resulting crypted byte array.
+ */
protected byte[] crypt(javax.crypto.Cipher cipher, byte[] bytes) {
try {
return cipher.doFinal(bytes);
@@ -130,6 +191,15 @@
}
}
+ /**
+ * Calls the {@link #init(javax.crypto.Cipher, int, java.security.Key)} and then
+ * {@link #crypt(javax.crypto.Cipher, byte[])}. Ensures that the key is never null by using the
+ * {@link #getKey() default key} if the method argument key is <code>null</code>.
+ * @param bytes the bytes to crypt
+ * @param mode the JDK Cipher mode
+ * @param key the key to use to do the cryption. If <code>null</code> the {@link #getKey() default key} will be used.
+ * @return the resulting crypted byte array
+ */
protected byte[] crypt(byte[] bytes, int mode, byte[] key) {
javax.crypto.Cipher cipher = newCipherInstance();
@@ -144,10 +214,21 @@
return crypt(cipher, bytes);
}
+ /**
+ * Generates a new {@link Key Key} suitable for this Cipher by calling
+ * {@link #generateNewKey() generateNewKey(128)} (uses a 128 bit size by default).
+ * @return a new {@link Key Key}, 128 bits in length.
+ */
public static Key generateNewKey() {
return generateNewKey(128);
}
+ /**
+ * Generates a new {@link Key Key} of the specified size suitable for this Cipher
+ * (based on the {@link #ALGORITHM ALGORITHM} using the JDK {@link KeyGenerator KeyGenerator}.
+ * @param keyBitSize the bit size of the key to create
+ * @return the created key suitable for use with this Cipher.
+ */
public static Key generateNewKey(int keyBitSize) {
KeyGenerator kg;
try {
@@ -160,6 +241,11 @@
return kg.generateKey();
}
+ /**
+ * Simple test main method to ensure functionality is correct. Should really be moved to a proper test case.
+ * @param unused ignored
+ * @throws Exception if anything unexpected happens.
+ */
public static void main(String[] unused) throws Exception {
Cipher cipher = new BlowfishCipher();
