You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@shiro.apache.org by lh...@apache.org on 2010/05/20 09:43:03 UTC
svn commit: r946554 - in /incubator/shiro/trunk:
core/src/main/java/org/apache/shiro/codec/
core/src/main/java/org/apache/shiro/config/
core/src/main/java/org/apache/shiro/io/
core/src/main/java/org/apache/shiro/session/mgt/
core/src/main/java/org/apac...
Author: lhazlewood
Date: Thu May 20 07:43:02 2010
New Revision: 946554
URL: http://svn.apache.org/viewvc?rev=946554&view=rev
Log:
Lots of JavaDoc enhancements
Added:
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/package-info.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/mgt/package-info.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/package-info.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/package-info.java
Modified:
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Base64.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Hex.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/config/Ini.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/io/ResourceUtils.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractNativeSessionManager.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractSessionManager.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ByteSource.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/LifecycleUtils.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/MapContext.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/PermissionUtils.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/SimpleByteSource.java
incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ThreadState.java
incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/AspectjAnnotationsAuthorizingMethodInterceptor.java
incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/BeforeAdviceMethodInvocationAdapter.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/DefaultWebSecurityManager.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilter.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilterChainManager.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/NamedFilterList.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/Cookie.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ProxiedFilterChain.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ServletContextSupport.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpServletRequest.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpSession.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/SimpleCookie.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/package-info.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/WebSubject.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/WebDelegatingSubject.java
incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/util/RequestPairSource.java
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Base64.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Base64.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Base64.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Base64.java Thu May 20 07:43:02 2010
@@ -19,22 +19,22 @@
package org.apache.shiro.codec;
/**
- * Provides Base64 encoding and decoding as defined by RFC 2045.
+ * Provides <a href="http://en.wikipedia.org/wiki/Base64">Base 64</a> encoding and decoding as defined by
+ * <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>.
* <p/>
- * <p>
* This class implements section <cite>6.8. Base64 Content-Transfer-Encoding</cite> from RFC 2045 <cite>Multipurpose
* Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies</cite> by Freed and Borenstein.
- * </p>
* <p/>
- * <p>This class was borrowed from Apache Commons Codec SVN repository (rev. 618419) with modifications
+ * This class was borrowed from Apache Commons Codec SVN repository (rev. 618419) with modifications
* to enable Base64 conversion without a full dependecny on Commons Codec. We didn't want to reinvent the wheel of
- * great work they've done, but also didn't want to force every Shiro user to depend on the commons-codec.jar</p>
+ * great work they've done, but also didn't want to force every Shiro user to depend on the commons-codec.jar
* <p/>
- * <p>As per the Apache 2.0 license, the original copyright notice and all author and copyright information have
- * remained in tact.</p>
+ * As per the Apache 2.0 license, the original copyright notice and all author and copyright information have
+ * remained in tact.
*
* @author Apache Software Foundation
* @author Les Hazlewood
+ * @see <a href="http://en.wikipedia.org/wiki/Base64">Wikipedia: Base 64</a>
* @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045</a>
* @since 0.9
*/
@@ -43,8 +43,8 @@ public class Base64 {
/**
* Chunk size per RFC 2045 section 6.8.
* <p/>
- * <p>The character limit does not count the trailing CRLF, but counts all other characters, including any
- * equal signs.</p>
+ * The character limit does not count the trailing CRLF, but counts all other characters, including any
+ * equal signs.
*
* @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 section 6.8</a>
*/
@@ -119,6 +119,7 @@ public class Base64 {
private static final byte[] lookUpBase64Alphabet = new byte[LOOKUPLENGTH];
// Populating the lookup and character arrays
+
static {
for (int i = 0; i < BASELENGTH; i++) {
base64Alphabet[i] = (byte) -1;
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Hex.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Hex.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Hex.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/codec/Hex.java Thu May 20 07:43:02 2010
@@ -19,17 +19,18 @@
package org.apache.shiro.codec;
/**
- * Hex encoder and decoder.
- *
- * <p>This class was borrowed from Apache Commons Codec SVN repository (rev. 560660 ) with modifications
+ * <a href="http://en.wikipedia.org/wiki/Hexadecimal">Hexadecimal</a> encoder and decoder.
+ * <p/>
+ * This class was borrowed from Apache Commons Codec SVN repository (rev. {@code 560660}) with modifications
* to enable Hex conversion without a full dependency on Commons Codec. We didn't want to reinvent the wheel of
- * great work they've done, but also didn't want to force every Shiro user to depend on the commons-codec.jar</p>
- *
- * <p>As per the Apache 2.0 license, the original copyright notice and all author and copyright information have
- * remained in tact.</p>
+ * great work they've done, but also didn't want to force every Shiro user to depend on the commons-codec.jar
+ * <p/>
+ * As per the Apache 2.0 license, the original copyright notice and all author and copyright information have
+ * remained in tact.
*
* @author Apache Software Foundation
* @author Les Hazlewood
+ * @see <a href="http://en.wikipedia.org/wiki/Hexadecimal">Wikipedia: Hexadecimal</a>
* @since 0.9
*/
public class Hex {
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/config/Ini.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/config/Ini.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/config/Ini.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/config/Ini.java Thu May 20 07:43:02 2010
@@ -31,7 +31,8 @@ import java.util.*;
* A class representing the <a href="http://en.wikipedia.org/wiki/INI_file">INI</a> text configuration format.
* <p/>
* An Ini instance is a map of {@link Ini.Section Section}s, keyed by section name. Each
- * {@code Section} is itself a map of {@code String} name/value pairs.
+ * {@code Section} is itself a map of {@code String} name/value pairs. Name/value pairs are guaranteed to be unique
+ * within each {@code Section} only - not across the entire {@code Ini} instance.
*
* @author The Apache Shiro Project (shiro-dev@incubator.apache.org)
* @since 1.0
@@ -50,10 +51,18 @@ public class Ini implements Map<String,
private final Map<String, Section> sections;
+ /**
+ * Creates a new empty {@code Ini} instance.
+ */
public Ini() {
this.sections = new LinkedHashMap<String, Section>();
}
+ /**
+ * Creates a new {@code Ini} instance with the specified defaults.
+ *
+ * @param defaults the default sections and/or key-value pairs to copy into the new instance.
+ */
public Ini(Ini defaults) {
this();
if (defaults == null) {
@@ -84,19 +93,45 @@ public class Ini implements Map<String,
return true;
}
+ /**
+ * Returns the names of all sections managed by this {@code Ini} instance or an empty collection if there are
+ * no sections.
+ *
+ * @return the names of all sections managed by this {@code Ini} instance or an empty collection if there are
+ * no sections.
+ */
public Set<String> getSectionNames() {
return Collections.unmodifiableSet(sections.keySet());
}
+ /**
+ * Returns the sections managed by this {@code Ini} instance or an empty collection if there are
+ * no sections.
+ *
+ * @return the sections managed by this {@code Ini} instance or an empty collection if there are
+ * no sections.
+ */
public Collection<Section> getSections() {
return Collections.unmodifiableCollection(sections.values());
}
+ /**
+ * Returns the {@link Section} with the given name or {@code null} if no section with that name exists.
+ *
+ * @param sectionName the name of the section to retrieve.
+ * @return the {@link Section} with the given name or {@code null} if no section with that name exists.
+ */
public Section getSection(String sectionName) {
String name = cleanName(sectionName);
return sections.get(name);
}
+ /**
+ * Ensures a section with the specified name exists, adding a new one if it does not yet exist.
+ *
+ * @param sectionName the name of the section to ensure existence
+ * @return the section created if it did not yet exist, or the existing Section that already existed.
+ */
public Section addSection(String sectionName) {
String name = cleanName(sectionName);
Section section = getSection(name);
@@ -107,6 +142,12 @@ public class Ini implements Map<String,
return section;
}
+ /**
+ * Removes the section with the specified name and returns it, or {@code null} if the section did not exist.
+ *
+ * @param sectionName the name of the section to remove.
+ * @return the section with the specified name or {@code null} if the section did not exist.
+ */
public Section removeSection(String sectionName) {
String name = cleanName(sectionName);
return this.sections.remove(name);
@@ -121,6 +162,15 @@ public class Ini implements Map<String,
return name;
}
+ /**
+ * Sets a name/value pair for the section with the given {@code sectionName}. If the section does not yet exist,
+ * it will be created. If the {@code sectionName} is null or empty, the name/value pair will be placed in the
+ * default (unnamed, empty string) section.
+ *
+ * @param sectionName the name of the section to add the name/value pair
+ * @param propertyName the name of the property to add
+ * @param propertyValue the property value
+ */
public void setSectionProperty(String sectionName, String propertyName, String propertyValue) {
String name = cleanName(sectionName);
Section section = getSection(name);
@@ -130,16 +180,42 @@ public class Ini implements Map<String,
section.put(propertyName, propertyValue);
}
+ /**
+ * Returns the value of the specified section property, or {@code null} if the section or property do not exist.
+ *
+ * @param sectionName the name of the section to retrieve to acquire the property value
+ * @param propertyName the name of the section property for which to return the value
+ * @return the value of the specified section property, or {@code null} if the section or property do not exist.
+ */
public String getSectionProperty(String sectionName, String propertyName) {
Section section = getSection(sectionName);
return section != null ? section.get(propertyName) : null;
}
+ /**
+ * Returns the value of the specified section property, or the {@code defaultValue} if the section or
+ * property do not exist.
+ *
+ * @param sectionName the name of the section to add the name/value pair
+ * @param propertyName the name of the property to add
+ * @param defaultValue the default value to return if the section or property do not exist.
+ * @return the value of the specified section property, or the {@code defaultValue} if the section or
+ * property do not exist.
+ */
public String getSectionProperty(String sectionName, String propertyName, String defaultValue) {
String value = getSectionProperty(sectionName, propertyName);
return value != null ? value : defaultValue;
}
+ /**
+ * Creates a new {@code Ini} instance loaded with the INI-formatted data in the resource at the given path. The
+ * resource path may be any value interpretable by the
+ * {@link ResourceUtils#getInputStreamForPath(String) ResourceUtils.getInputStreamForPath} method.
+ *
+ * @param resourcePath the resource location of the INI data to load when creating the {@code Ini} instance.
+ * @return a new {@code Ini} instance loaded with the INI-formatted data in the resource at the given path.
+ * @throws ConfigurationException if the path cannot be loaded into an {@code Ini} instance.
+ */
public static Ini fromResourcePath(String resourcePath) throws ConfigurationException {
if (!StringUtils.hasLength(resourcePath)) {
throw new IllegalArgumentException("Resource Path argument cannot be null or empty.");
@@ -149,6 +225,14 @@ public class Ini implements Map<String,
return ini;
}
+ /**
+ * Loads data from the specified resource path into this current {@code Ini} instance. The
+ * resource path may be any value interpretable by the
+ * {@link ResourceUtils#getInputStreamForPath(String) ResourceUtils.getInputStreamForPath} method.
+ *
+ * @param resourcePath the resource location of the INI data to load into this instance.
+ * @throws ConfigurationException if the path cannot be loaded
+ */
public void loadFromPath(String resourcePath) throws ConfigurationException {
InputStream is;
try {
@@ -159,10 +243,23 @@ public class Ini implements Map<String,
load(is);
}
+ /**
+ * Loads the specified raw INI-formatted text into this instance.
+ *
+ * @param iniConfig the raw INI-formatted text to load into this instance.
+ * @throws ConfigurationException if the text cannot be loaded
+ */
public void load(String iniConfig) throws ConfigurationException {
load(new Scanner(iniConfig));
}
+ /**
+ * Loads the INI-formatted text backed by the given InputStream into this instance. This implementation will
+ * close the input stream after it has finished loading.
+ *
+ * @param is the {@code InputStream} from which to read the INI-formatted text
+ * @throws ConfigurationException if unable
+ */
public void load(InputStream is) throws ConfigurationException {
if (is == null) {
throw new NullPointerException("InputStream argument cannot be null.");
@@ -176,6 +273,12 @@ public class Ini implements Map<String,
load(isr);
}
+ /**
+ * Loads the INI-formatted text backed by the given Reader into this instance. This implementation will close the
+ * reader after it has finished loading.
+ *
+ * @param reader the {@code Reader} from which to read the INI-formatted text
+ */
public void load(Reader reader) {
Scanner scanner = new Scanner(reader);
try {
@@ -223,6 +326,12 @@ public class Ini implements Map<String,
}
}
+ /**
+ * Loads the INI-formatted text backed by the given Scanner. This implementation will close the
+ * scanner after it has finished loading.
+ *
+ * @param scanner the {@code Scanner} from which to read the INI-formatted text
+ */
public void load(Scanner scanner) {
String sectionName = DEFAULT_SECTION_NAME;
@@ -348,6 +457,10 @@ public class Ini implements Map<String,
return Collections.unmodifiableSet(this.sections.entrySet());
}
+ /**
+ * An {@code Ini.Section} is String-key-to-String-value Map, identifiable by a
+ * {@link #getName() name} unique within an {@link Ini} instance.
+ */
public class Section implements Map<String, String> {
private final String name;
private final Map<String, String> props;
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/io/ResourceUtils.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/io/ResourceUtils.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/io/ResourceUtils.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/io/ResourceUtils.java Thu May 20 07:43:02 2010
@@ -18,43 +18,43 @@
*/
package org.apache.shiro.io;
+import org.apache.shiro.util.ClassUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-
-import org.apache.shiro.util.ClassUtils;
-
/**
- * Static helper methods for loading resources.
+ * Static helper methods for loading {@code Stream}-backed resources.
*
* @author Jeremy Haile
+ * @author Les Hazlewood
+ * @see #getInputStreamForPath(String)
* @since 0.2
*/
public class ResourceUtils {
- //TODO complete JavaDoc
-
/**
- * Resource path prefix that specifies to load from a classpath location, value is <b><code>classpath:</code></b>
+ * Resource path prefix that specifies to load from a classpath location, value is <b>{@code classpath:}</b>
*/
public static final String CLASSPATH_PREFIX = "classpath:";
/**
- * Resource path prefix that specifies to load from a url location, value is <b><code>url:</code></b>
+ * Resource path prefix that specifies to load from a url location, value is <b>{@code url:}</b>
*/
public static final String URL_PREFIX = "url:";
/**
- * Resource path prefix that specifies to load from a file location, value is <b><code>file:</code></b>
+ * Resource path prefix that specifies to load from a file location, value is <b>{@code file:}</b>
*/
public static final String FILE_PREFIX = "file:";
- /** Private internal log instance. */
+ /**
+ * Private internal log instance.
+ */
private static final Logger log = LoggerFactory.getLogger(ResourceUtils.class);
-
/**
* Prevent instantiation.
*/
@@ -62,15 +62,16 @@ public class ResourceUtils {
}
/**
- * Returns <code>true</code> if the resource path is not null and starts with one of the recognized
- * resource prefixes ({@link #CLASSPATH_PREFIX CLASSPATH_PREFIX},
- * {@link #URL_PREFIX URL_PREFIX}, or {@link #FILE_PREFIX FILE_PREFIX}), <code>false</code> otherwise.
+ * Returns {@code true} if the resource path is not null and starts with one of the recognized
+ * resource prefixes ({@link #CLASSPATH_PREFIX CLASSPATH_PREFIX},
+ * {@link #URL_PREFIX URL_PREFIX}, or {@link #FILE_PREFIX FILE_PREFIX}), {@code false} otherwise.
*
* @param resourcePath the resource path to check
- * @return <code>true</code> if the resource path is not null and starts with one of the recognized
- * resource prefixes, <code>false</code> otherwise.
+ * @return {@code true} if the resource path is not null and starts with one of the recognized
+ * resource prefixes, {@code false} otherwise.
* @since 0.9
*/
+ @SuppressWarnings({"UnusedDeclaration"})
public static boolean hasResourcePrefix(String resourcePath) {
return resourcePath != null &&
(resourcePath.startsWith(CLASSPATH_PREFIX) ||
@@ -79,9 +80,11 @@ public class ResourceUtils {
}
/**
- * Returns <code>true</code> if the resource at the specified path exists, <code>false</code> otherwise.
+ * Returns {@code true} if the resource at the specified path exists, {@code false} otherwise. This
+ * method supports scheme prefixes on the path as defined in {@link #getInputStreamForPath(String)}.
+ *
* @param resourcePath the path of the resource to check.
- * @return <code>true</code> if the resource at the specified path exists, <code>false</code> otherwise.
+ * @return {@code true} if the resource at the specified path exists, {@code false} otherwise.
* @since 0.9
*/
public static boolean resourceExists(String resourcePath) {
@@ -107,9 +110,12 @@ public class ResourceUtils {
/**
- * Returns the InputStream for the resource represented by the specified path.
- *
- * <p>The supporting prefixes are defined as as *_PREFIX constants in this class.</p>
+ * Returns the InputStream for the resource represented by the specified path, supporting scheme
+ * prefixes that direct how to acquire the input stream
+ * ({@link #CLASSPATH_PREFIX CLASSPATH_PREFIX},
+ * {@link #URL_PREFIX URL_PREFIX}, or {@link #FILE_PREFIX FILE_PREFIX}). If the path is not prefixed by one
+ * of these schemes, the path is assumed to be a file-based path that can be loaded with a
+ * {@link FileInputStream FileInputStream}.
*
* @param resourcePath the String path representing the resource to obtain.
* @return the InputStraem for the specified resource.
@@ -139,11 +145,9 @@ public class ResourceUtils {
}
private static InputStream loadFromFile(String path) throws IOException {
-
if (log.isDebugEnabled()) {
log.debug("Opening file [" + path + "]...");
}
-
return new FileInputStream(path);
}
@@ -162,6 +166,13 @@ public class ResourceUtils {
return resourcePath.substring(resourcePath.indexOf(":") + 1);
}
+ /**
+ * Convenience method that closes the specified {@link InputStream InputStream}, logging any
+ * {@link IOException IOException} that might occur. If the {@code InputStream}
+ * argument is {@code null}, this method does nothing. It returns quietly in all cases.
+ *
+ * @param is the {@code InputStream} to close, logging any {@code IOException} that might occur.
+ */
public static void close(InputStream is) {
if (is != null) {
try {
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractNativeSessionManager.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractNativeSessionManager.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractNativeSessionManager.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractNativeSessionManager.java Thu May 20 07:43:02 2010
@@ -27,6 +27,10 @@ import java.util.Collections;
import java.util.Date;
/**
+ * Abstract implementation supporting the {@link NativeSessionManager NativeSessionManager} interface, supporting
+ * {@link SessionListener SessionListener}s and application of the
+ * {@link #getGlobalSessionTimeout() globalSessionTimeout}.
+ *
* @author Les Hazlewood
* @since 1.0
*/
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractSessionManager.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractSessionManager.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractSessionManager.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/session/mgt/AbstractSessionManager.java Thu May 20 07:43:02 2010
@@ -21,6 +21,10 @@ package org.apache.shiro.session.mgt;
import org.apache.shiro.session.Session;
/**
+ * Base abstract class of the {@link SessionManager SessionManager} interface, enabling configuration of an
+ * application-wide {@link #getGlobalSessionTimeout() globalSessionTimeout}. Default global session timeout is
+ * {@code 30} minutes.
+ *
* @author Les Hazlewood
* @since 0.1
*/
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ByteSource.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ByteSource.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ByteSource.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ByteSource.java Thu May 20 07:43:02 2010
@@ -26,10 +26,29 @@ package org.apache.shiro.util;
*/
public interface ByteSource {
+ /**
+ * Returns the wrapped byte array.
+ *
+ * @return the wrapped byte array.
+ */
public byte[] getBytes();
+ /**
+ * Returns the <a href="http://en.wikipedia.org/wiki/Hexadecimal">Hex</a>-formatted String representation of the
+ * underlying wrapped byte array.
+ *
+ * @return the <a href="http://en.wikipedia.org/wiki/Hexadecimal">Hex</a>-formatted String representation of the
+ * underlying wrapped byte array.
+ */
@SuppressWarnings({"UnusedDeclaration"})
public String toHex();
+ /**
+ * Returns the <a href="http://en.wikipedia.org/wiki/Base64">Base 64</a>-formatted String representation of the
+ * underlying wrapped byte array.
+ *
+ * @return the <a href="http://en.wikipedia.org/wiki/Base64">Base 64</a>-formatted String representation of the
+ * underlying wrapped byte array.
+ */
public String toBase64();
}
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/LifecycleUtils.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/LifecycleUtils.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/LifecycleUtils.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/LifecycleUtils.java Thu May 20 07:43:02 2010
@@ -18,16 +18,17 @@
*/
package org.apache.shiro.util;
-import java.util.Collection;
-
+import org.apache.shiro.ShiroException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
-import org.apache.shiro.ShiroException;
+import java.util.Collection;
/**
- * TODO - complete JavaDoc
+ * Utility class to help call {@link org.apache.shiro.util.Initializable#init() Initializable.init()} and
+ * {@link org.apache.shiro.util.Destroyable#destroy() Destroyable.destroy()} methods cleanly on any object.
+ *
* @author Les Hazlewood
* @since 0.2
*/
@@ -35,25 +36,25 @@ public abstract class LifecycleUtils {
private static final Logger log = LoggerFactory.getLogger(LifecycleUtils.class);
- public static void init(Object o) throws ShiroException
- {
+ public static void init(Object o) throws ShiroException {
if (o instanceof Initializable) {
init((Initializable) o);
}
}
- public static void init(Initializable initializable) throws ShiroException
- {
+ public static void init(Initializable initializable) throws ShiroException {
initializable.init();
}
/**
- * @param c
- * @throws org.apache.shiro.ShiroException
+ * Calls {@link #init(Object) init} for each object in the collection. If the collection is {@code null} or empty,
+ * this method returns quietly.
+ *
+ * @param c the collection containing objects to {@link #init init}.
+ * @throws ShiroException if unable to initialize one or more instances.
* @since 0.9
*/
- public static void init(Collection c) throws ShiroException
- {
+ public static void init(Collection c) throws ShiroException {
if (c == null || c.isEmpty()) {
return;
}
@@ -82,8 +83,8 @@ public abstract class LifecycleUtils {
}
/**
- * Calls {@link #destroy(Object) destroy} for each object in the collection. If the collection is <code>null</code> or
- * empty, this method returns quietly.
+ * Calls {@link #destroy(Object) destroy} for each object in the collection.
+ * If the collection is {@code null} or empty, this method returns quietly.
*
* @param c the collection of objects to destroy.
* @since 0.9
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/MapContext.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/MapContext.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/MapContext.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/MapContext.java Thu May 20 07:43:02 2010
@@ -22,9 +22,12 @@ import java.io.Serializable;
import java.util.*;
/**
- * TODO - Class JavaDoc
+ * A {@code MapContext} provides a common base for context-based data storage in a {@link Map}. Type-safe attribute
+ * retrieval is provided for subclasses with the {@link #getTypedValue(String, Class)} method.
*
* @author Les Hazlewood
+ * @see org.apache.shiro.subject.SubjectContext SubjectContext
+ * @see org.apache.shiro.session.mgt.SessionContext SessionContext
* @since 1.0
*/
public class MapContext implements Map<String, Object>, Serializable {
@@ -44,6 +47,15 @@ public class MapContext implements Map<S
}
}
+ /**
+ * Performs a {@link #get get} operation but additionally ensures that the value returned is of the specified
+ * {@code type}. If there is no value, {@code null} is returned.
+ *
+ * @param key the attribute key to look up a value
+ * @param type the expected type of the value
+ * @param <E> the expected type of the value
+ * @return the typed value or {@code null} if the attribute does not exist.
+ */
@SuppressWarnings({"unchecked"})
protected <E> E getTypedValue(String key, Class<E> type) {
E found = null;
@@ -60,6 +72,12 @@ public class MapContext implements Map<S
return found;
}
+ /**
+ * Places a value in this context map under the given key only if the given {@code value} argument is not null.
+ *
+ * @param key the attribute key under which the non-null value will be stored
+ * @param value the non-null value to store. If {@code null}, this method does nothing and returns immediately.
+ */
protected void nullSafePut(String key, Object value) {
if (value != null) {
put(key, value);
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/PermissionUtils.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/PermissionUtils.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/PermissionUtils.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/PermissionUtils.java Thu May 20 07:43:02 2010
@@ -18,17 +18,18 @@
*/
package org.apache.shiro.util;
+import org.apache.shiro.authz.Permission;
+import org.apache.shiro.authz.permission.PermissionResolver;
+
import java.util.Arrays;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.Set;
-import org.apache.shiro.authz.Permission;
-import org.apache.shiro.authz.permission.PermissionResolver;
-
/**
- * TODO - comlete JavaDoc
+ * Utility class to help with String-to-Permission object resolution.
+ *
* @author Les Hazlewood
* @author Jeremy Haile
* @since 0.1
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/SimpleByteSource.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/SimpleByteSource.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/SimpleByteSource.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/SimpleByteSource.java Thu May 20 07:43:02 2010
@@ -24,10 +24,12 @@ import org.apache.shiro.codec.Hex;
import java.util.Arrays;
/**
- * TODO - Class JavaDoc
+ * Very simple {@link ByteSource ByteSource} implementation that maintains an internal {@code byte[]} array and uses the
+ * {@link Hex Hex} and {@link Base64 Base64} codec classes to support the
+ * {@link #toHex() toHex()} and {@link #toBase64() toBase64()} implementations.
*
* @author Les Hazlewood
- * @since Apr 12, 2010 2:35:19 PM
+ * @since 1.0
*/
public class SimpleByteSource implements ByteSource {
Modified: incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ThreadState.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ThreadState.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ThreadState.java (original)
+++ incubator/shiro/trunk/core/src/main/java/org/apache/shiro/util/ThreadState.java Thu May 20 07:43:02 2010
@@ -75,7 +75,9 @@ public interface ThreadState {
void restore();
/**
- * Clears a thread's state modifications entirely.
+ * Completely clears/removes the {@code ThreadContext} state. Typically this method should
+ * only be called in special cases - it is more 'correct' to {@link #restore restore} a thread to its previous
+ * state than to clear it entirely.
*/
void clear();
Modified: incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/AspectjAnnotationsAuthorizingMethodInterceptor.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/AspectjAnnotationsAuthorizingMethodInterceptor.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/AspectjAnnotationsAuthorizingMethodInterceptor.java (original)
+++ incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/AspectjAnnotationsAuthorizingMethodInterceptor.java Thu May 20 07:43:02 2010
@@ -34,7 +34,7 @@ import java.util.Arrays;
*
* @author J-C Desrochers
* @author Kalle Korhonen
- * @since 1.0.0
+ * @since 1.0
*/
public class AspectjAnnotationsAuthorizingMethodInterceptor extends AnnotationsAuthorizingMethodInterceptor {
/**
Modified: incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/BeforeAdviceMethodInvocationAdapter.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/BeforeAdviceMethodInvocationAdapter.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/BeforeAdviceMethodInvocationAdapter.java (original)
+++ incubator/shiro/trunk/support/aspectj/src/main/java/org/apache/shiro/aspectj/BeforeAdviceMethodInvocationAdapter.java Thu May 20 07:43:02 2010
@@ -26,10 +26,10 @@ import org.aspectj.lang.reflect.MethodSi
import java.lang.reflect.Method;
/**
- * Helper class that adapts and aspectj {@link JoinPoint}.
+ * Helper class that adapts an AspectJ {@link JoinPoint JoinPoint}.
*
* @author J-C Desrochers
- * @since 1.0.0
+ * @since 1.0
*/
public class BeforeAdviceMethodInvocationAdapter implements MethodInvocation {
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/DefaultWebSecurityManager.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/DefaultWebSecurityManager.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/DefaultWebSecurityManager.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/DefaultWebSecurityManager.java Thu May 20 07:43:02 2010
@@ -46,8 +46,8 @@ import java.util.Collection;
/**
- * SecurityManager implementation that should be used in web-based applications or any application that requires
- * HTTP connectivity (SOAP, http remoting, etc).
+ * Default {@link WebSecurityManager WebSecurityManager} implementation used in web-based applications or any
+ * application that requires HTTP connectivity (SOAP, http remoting, etc).
*
* @author Les Hazlewood
* @since 0.2
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilter.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilter.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilter.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilter.java Thu May 20 07:43:02 2010
@@ -35,8 +35,8 @@ import java.util.LinkedHashMap;
import java.util.Map;
/**
- * Enum representing all of the default Shiro Filter instances available to web applications. Each filter is
- * typically accessible by the {@link #name() name} of the enum constant.
+ * Enum representing all of the default Shiro Filter instances available to web applications. Each filter instance is
+ * typically accessible in configuration the {@link #name() name} of the enum constant.
*
* @author Les Hazlewood
* @since 1.0
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilterChainManager.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilterChainManager.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilterChainManager.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/DefaultFilterChainManager.java Thu May 20 07:43:02 2010
@@ -38,6 +38,13 @@ import java.util.Set;
import static org.apache.shiro.util.StringUtils.split;
/**
+ * Default {@link FilterChainManager} implementation maintaining a map of {@link Filter Filter} instances
+ * (key: filter name, value: Filter) as well as a map of {@link NamedFilterList NamedFilterList}s created from these
+ * {@code Filter}s (key: filter chain name, value: NamedFilterList). The {@code NamedFilterList} is essentially a
+ * {@link FilterChain} that also has a name property by which it can be looked up.
+ *
+ * @author Les Hazlewood
+ * @see NamedFilterList
* @since 1.0
*/
public class DefaultFilterChainManager implements FilterChainManager {
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/NamedFilterList.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/NamedFilterList.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/NamedFilterList.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/NamedFilterList.java Thu May 20 07:43:02 2010
@@ -27,6 +27,7 @@ import java.util.List;
* {@link #getName() name}. It has the ability to generate new {@link FilterChain} instances reflecting this list's
* filter order via the {@link #proxy proxy} method.
*
+ * @author Les Hazlewood
* @since 1.0
*/
public interface NamedFilterList extends List<Filter> {
Added: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/package-info.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/package-info.java?rev=946554&view=auto
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/package-info.java (added)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/filter/mgt/package-info.java Thu May 20 07:43:02 2010
@@ -0,0 +1,26 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * The filter 'mgt' (management) package contains components used in managing Filters that are available for
+ * filter chain construction, the filter chains themselves, as well as resolving filter chains based by name.
+ *
+ * @see FilterChainManager
+ * @see FilterChainResolver
+ */
+package org.apache.shiro.web.filter.mgt;
\ No newline at end of file
Added: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/mgt/package-info.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/mgt/package-info.java?rev=946554&view=auto
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/mgt/package-info.java (added)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/mgt/package-info.java Thu May 20 07:43:02 2010
@@ -0,0 +1,23 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Components supporting web-specific
+ * {@link org.apache.shiro.mgt.SecurityManager SecurityManager} implementations.
+ */
+package org.apache.shiro.web.mgt;
\ No newline at end of file
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/Cookie.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/Cookie.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/Cookie.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/Cookie.java Thu May 20 07:43:02 2010
@@ -22,7 +22,11 @@ import javax.servlet.http.HttpServletReq
import javax.servlet.http.HttpServletResponse;
/**
- * TODO - Class JavaDoc
+ * Interface representing HTTP cookie operations, supporting pojo-style getters and setters for all
+ * attributes which includes <a href="http://www.owasp.org/index.php/HttpOnly">HttpOnly</a> support.
+ * This allows Shiro to set <a href="http://www.owasp.org/index.php/HttpOnly">HttpOnly</a> cookies even on
+ * Servlet containers based on the {@code 2.4} and {@code 2.5} API (Servlet API 'native' support was only introduced in
+ * the {@code 2.6} specification).
*
* @author Les Hazlewood
* @since 1.0
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ProxiedFilterChain.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ProxiedFilterChain.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ProxiedFilterChain.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ProxiedFilterChain.java Thu May 20 07:43:02 2010
@@ -26,6 +26,11 @@ import java.io.IOException;
import java.util.List;
/**
+ * A proxied filter chain is a {@link FilterChain} instance that proxies an original {@link FilterChain} as well
+ * as a {@link List List} of other {@link Filter Filter}s that might need to execute prior to the final wrapped
+ * original chain. It allows a list of filters to execute before continuing the original (proxied)
+ * {@code FilterChain} instance.
+ *
* @author Les Hazlewood
* @since 0.9
*/
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ServletContextSupport.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ServletContextSupport.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ServletContextSupport.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ServletContextSupport.java Thu May 20 07:43:02 2010
@@ -21,7 +21,7 @@ package org.apache.shiro.web.servlet;
import javax.servlet.ServletContext;
/**
- * TODO - class javadoc
+ * Base implementation for any components that need to access the web application's {@link ServletContext ServletContext}.
*
* @author Les Hazlewood
* @since 0.2
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpServletRequest.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpServletRequest.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpServletRequest.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpServletRequest.java Thu May 20 07:43:02 2010
@@ -30,6 +30,11 @@ import java.security.Principal;
/**
+ * A {@code ShiroHttpServletRequest} wraps the Servlet container's original {@code ServletRequest} instance, but ensures
+ * that all {@link HttpServletRequest} invocations that require Shiro's support ({@link #getRemoteUser getRemoteUser},
+ * {@link #getSession getSession}, etc) can be executed first by Shiro as necessary before allowing the underlying
+ * Servlet container instance's method to be invoked.
+ *
* @author Les Hazlewood
* @since 0.2
*/
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpSession.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpSession.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpSession.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/ShiroHttpSession.java Thu May 20 07:43:02 2010
@@ -31,9 +31,10 @@ import java.util.*;
/**
- * Wrapper class that uses a Shiro session under the hood for all session operations instead of the
- * Servlet Container's session mechanism. This is preferred in heterogeneous client environments where the Session
- * is used on both the business tier as well as in multiple client technologies (web, swing, flash, etc).
+ * Wrapper class that uses a Shiro {@link Session Session} under the hood for all session operations instead of the
+ * Servlet Container's session mechanism. This is required in heterogeneous client environments where the Session
+ * is used on both the business tier as well as in multiple client technologies (web, swing, flash, etc) since
+ * Servlet container sessions alone cannot support this feature.
*
* @author Les Hazlewood
* @since 0.2
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/SimpleCookie.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/SimpleCookie.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/SimpleCookie.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/SimpleCookie.java Thu May 20 07:43:02 2010
@@ -31,7 +31,10 @@ import java.util.Date;
import java.util.TimeZone;
/**
- * TODO - Class JavaDoc
+ * Default {@link Cookie Cookie} implementation. 'HttpOnly' is supported out of the box, even on
+ * Servlet {@code 2.4} and {@code 2.5} container implementations, using raw header writing logic and not
+ * {@link javax.servlet.http.Cookie javax.servlet.http.Cookie} objects (which only has 'HttpOnly' support in Servlet
+ * {@code 2.6} specifications and above).
*
* @author Les Hazlewood
* @since 1.0
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/package-info.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/package-info.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/package-info.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/servlet/package-info.java Thu May 20 07:43:02 2010
@@ -17,7 +17,8 @@
* under the License.
*/
/**
- * Support implementations that depend heavily on the <tt>javax.servlet.*</tt> API and are meant to be
- * directly used in web.xml (Servlet Filters, Servlet Context Listeners, Servlets, etc)
+ * Shiro-specific implementations of the Servlet API (Servlet Filters, et al).
+ *
+ * @see IniShiroFilter
*/
package org.apache.shiro.web.servlet;
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/WebSubject.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/WebSubject.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/WebSubject.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/WebSubject.java Thu May 20 07:43:02 2010
@@ -32,6 +32,7 @@ import javax.servlet.ServletResponse;
* A {@code WebSubject} represents a Subject instance that was acquired as a result of an incoming
* {@link ServletRequest}.
*
+ * @author Les Hazlewood
* @since 1.0
*/
public interface WebSubject extends Subject, RequestPairSource {
@@ -50,12 +51,38 @@ public interface WebSubject extends Subj
*/
ServletResponse getServletResponse();
+ /**
+ * A {@code WebSubject.Builder} performs the same function as a {@link Subject.Builder Subject.Builder}, but
+ * additionally ensures that the Servlet request/response pair that is triggering the Subject instance's creation
+ * is retained for use by internal Shiro components as necessary.
+ */
public static class Builder extends Subject.Builder {
+ /**
+ * Constructs a new {@code Web.Builder} instance using the {@link SecurityManager SecurityManager} obtained by
+ * calling {@code SecurityUtils.}{@link SecurityUtils#getSecurityManager() getSecurityManager()}. If you want
+ * to specify your own SecurityManager instance, use the
+ * {@link #Builder(SecurityManager, ServletRequest, ServletResponse)} constructor instead.
+ *
+ * @param request the incoming ServletRequest that will be associated with the built {@code WebSubject} instance.
+ * @param response the outgoing ServletRequest paired with the ServletRequest that will be associated with the
+ * built {@code WebSubject} instance.
+ */
public Builder(ServletRequest request, ServletResponse response) {
this(SecurityUtils.getSecurityManager(), request, response);
}
+ /**
+ * Constructs a new {@code Web.Builder} instance using the specified {@code SecurityManager} instance to
+ * create the {@link WebSubject WebSubject} instance.
+ *
+ * @param securityManager the {@code SecurityManager SecurityManager} instance to use to build the
+ * {@code WebSubject} instance.
+ * @param request the incoming ServletRequest that will be associated with the built {@code WebSubject}
+ * instance.
+ * @param response the outgoing ServletRequest paired with the ServletRequest that will be associated
+ * with the built {@code WebSubject} instance.
+ */
public Builder(SecurityManager securityManager, ServletRequest request, ServletResponse response) {
super(securityManager);
if (request == null) {
@@ -68,11 +95,26 @@ public interface WebSubject extends Subj
setResponse(response);
}
+ /**
+ * Overrides the parent implementation to return a new instance of a
+ * {@link DefaultWebSubjectContext DefaultWebSubjectContext} to account for the additional request/response
+ * pair.
+ *
+ * @return a new instance of a {@link DefaultWebSubjectContext DefaultWebSubjectContext} to account for the
+ * additional request/response pair.
+ */
@Override
protected SubjectContext newSubjectContextInstance() {
return new DefaultWebSubjectContext();
}
+ /**
+ * Called by the {@code WebSubject.Builder} constructor, this method places the request object in the
+ * context map for later retrieval.
+ *
+ * @param request the incoming ServletRequest that triggered the creation of the {@code WebSubject} instance.
+ * @return 'this' for method chaining.
+ */
protected Builder setRequest(ServletRequest request) {
if (request != null) {
((WebSubjectContext) getSubjectContext()).setServletRequest(request);
@@ -80,6 +122,14 @@ public interface WebSubject extends Subj
return this;
}
+ /**
+ * Called by the {@code WebSubject.Builder} constructor, this method places the response object in the
+ * context map for later retrieval.
+ *
+ * @param response the outgoing ServletRequest paired with the ServletRequest that triggered the creation of
+ * the {@code WebSubject} instance.
+ * @return 'this' for method chaining.
+ */
protected Builder setResponse(ServletResponse response) {
if (response != null) {
((WebSubjectContext) getSubjectContext()).setServletResponse(response);
@@ -87,6 +137,14 @@ public interface WebSubject extends Subj
return this;
}
+ /**
+ * Returns {@link #buildSubject() super.buildSubject()}, but additionally ensures that the returned instance
+ * is an {@code instanceof} {@link WebSubject WebSubject} and to support a type-safe method so a caller
+ * does not have to cast. Per the parent class's method JavaDoc, this method will return a new instance
+ * each time it is called.
+ *
+ * @return a new {@link WebSubject WebSubject} instance built by this {@code Builder}.
+ */
public WebSubject buildWebSubject() {
Subject subject = super.buildSubject();
if (!(subject instanceof WebSubject)) {
Added: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/package-info.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/package-info.java?rev=946554&view=auto
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/package-info.java (added)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/package-info.java Thu May 20 07:43:02 2010
@@ -0,0 +1,25 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Web-specific {@link org.apache.shiro.subject.Subject Subject} interfaces to enable {@code Subject} use in web
+ * environments.
+ *
+ * @see WebSubject
+ */
+package org.apache.shiro.web.subject;
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/WebDelegatingSubject.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/WebDelegatingSubject.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/WebDelegatingSubject.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/WebDelegatingSubject.java Thu May 20 07:43:02 2010
@@ -32,6 +32,9 @@ import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
/**
+ * Default {@link WebSubject WebSubject} implementation that additional ensures the ability to retain a
+ * servlet request/response pair to be used by internal shiro components as necessary during the request execution.
+ *
* @since 1.0
*/
public class WebDelegatingSubject extends DelegatingSubject implements WebSubject {
Added: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/package-info.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/package-info.java?rev=946554&view=auto
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/package-info.java (added)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/subject/support/package-info.java Thu May 20 07:43:02 2010
@@ -0,0 +1,24 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+/**
+ * Supporting implementations of {@code org.apache.shiro.web.subject} package interfaces.
+ *
+ * @see WebDelegatingSubject
+ */
+package org.apache.shiro.web.subject.support;
Modified: incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/util/RequestPairSource.java
URL: http://svn.apache.org/viewvc/incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/util/RequestPairSource.java?rev=946554&r1=946553&r2=946554&view=diff
==============================================================================
--- incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/util/RequestPairSource.java (original)
+++ incubator/shiro/trunk/web/src/main/java/org/apache/shiro/web/util/RequestPairSource.java Thu May 20 07:43:02 2010
@@ -19,12 +19,28 @@ import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
/**
+ * A {@code RequestPairSource} is a component that can supply a {@link ServletRequest ServletRequest} and
+ * {@link ServletResponse ServletResponse} pair associated with a currently executing request. This is used for
+ * framework development support and is rarely used by end-users.
+ *
* @author Les Hazlewood
* @since 1.0
*/
public interface RequestPairSource {
+ /**
+ * Returns the incoming {@link ServletRequest ServletRequest} associated with the component.
+ *
+ * @return the incoming {@link ServletRequest ServletRequest} associated with the component.
+ */
ServletRequest getServletRequest();
+ /**
+ * Returns the outgoing {@link ServletResponse ServletResponse} paired with the incoming
+ * {@link #getServletRequest() servletRequest}.
+ *
+ * @return the outgoing {@link ServletResponse ServletResponse} paired with the incoming
+ * {@link #getServletRequest() servletRequest}.
+ */
ServletResponse getServletResponse();
}