ifheader.java

jsr170接口的java实现。是个apache的开源项目。

	 */
	protected String getValue() {
	    return value;
	}

        /**
         * Returns the String represenation of this entry. This method uses the
         * {@link #getType} to build the string representation.
         *
         * @return the String represenation of this entry.
         */
        public String toString() {
            if (stringValue == null) {
                stringValue = getType() + ": " + (positive?"":"!") + value;
            }
            return stringValue;
        }
    }

    /**
     * The <code>IfListEntryToken</code> extends the {@link IfListEntry}
     * abstract class to represent an entry for token matching.
     */
    private static class IfListEntryToken extends IfListEntry {

        /**
         * Creates a token matching entry.
         *
         * @param token The token value pertinent to this instance.
         * @param positive <code>true</code> if this is a positive match entry.
         */
        IfListEntryToken(String token, boolean positive) {
            super(token, positive);
        }

        /**
         * Matches the token parameter to the stored token value and returns
         * <code>true</code> if the values match and if the match is positive.
         * <code>true</code> is also returned for negative matches if the values
         * do not match.
         *
         * @param token The token value to compare
         * @param etag The etag value to compare, which is ignored in this
         *      implementation.
         *
         * @return <code>true</code> if the token matches the <em>IfList</em>
         *      entry's token value.
         */
        public boolean match(String token, String etag) {
            return super.match(token);
        }

        /**
         * Returns the type name of this implementation, which is fixed to
         * be <em>Token</em>.
         *
         * @return The fixed string <em>Token</em> as the type name.
         */
        protected String getType() {
            return "Token";
        }
    }

    /**
     * The <code>IfListEntryToken</code> extends the {@link IfListEntry}
     * abstract class to represent an entry for etag matching.
     */
    private static class IfListEntryEtag extends IfListEntry {

        /**
         * Creates an etag matching entry.
         *
         * @param etag The etag value pertinent to this instance.
         * @param positive <code>true</code> if this is a positive match entry.
         */
        IfListEntryEtag(String etag, boolean positive) {
            super(etag, positive);
        }

        /**
         * Matches the etag parameter to the stored etag value and returns
         * <code>true</code> if the values match and if the match is positive.
         * <code>true</code> is also returned for negative matches if the values
         * do not match.
         *
         * @param token The token value to compare, which is ignored in this
         *      implementation.
         * @param etag The etag value to compare
         *
         * @return <code>true</code> if the etag matches the <em>IfList</em>
         *      entry's etag value.
         */
        public boolean match(String token, String etag) {
            return super.match(etag);
        }

        /**
         * Returns the type name of this implementation, which is fixed to
         * be <em>ETag</em>.
         *
         * @return The fixed string <em>ETag</em> as the type name.
         */
        protected String getType() {
            return "ETag";
        }
    }

    /**
     * The <code>IfList</code> class extends the <code>ArrayList</code> class
     * with the limitation to only support adding {@link IfListEntry} objects
     * and adding a {@link #match} method.
     * <p>
     * This class is a container for data contained in the <em>If</em>
     * production <em>IfList</em>
     * <pre>
         IfList = { [ "Not" ] ( ("<" Word ">" ) | ( "[" Word "]" ) ) } .
     * </pre>
     * <p>
     */
    private static class IfList extends ArrayList {

        /**
         * Throws an <code>IllegalStateException</code> because only
         * {@link IfListEntry} objects are supported in this list.
         *
         * @param o The <code>Object</code> to add.
         * @return <code>true</code> if successfull
         *
         * @throws IllegalStateException because only {@link IfListEntry}
         *      objects are supported in this list.
         */
        public boolean add(Object o) {
            throw new IllegalArgumentException("Only IfListEntry instances allowed");
        }

        /**
         * Throws an <code>IllegalStateException</code> because only
         * {@link IfListEntry} objects are supported in this list.
         *
         * @param index The position at which to add the object.
         * @param element The <code>Object</code> to add.
         *
         * @throws IllegalStateException because only {@link IfListEntry}
         *      objects are supported in this list.
         */
        public void add(int index, Object element) {
            throw new IllegalArgumentException("Only IfListEntry instances allowed");
        }

        /**
         * Adds the {@link IfListEntry} at the end of the list.
         *
         * @param entry The {@link IfListEntry} to add to the list
         *
         * @return <code>true</code> (as per the general contract of
         *      Collection.add).
         */
        public boolean add(IfListEntry entry) {
            return super.add(entry);
        }

        /**
         * Adds the {@link IfListEntry} at the indicated position of the list.
         *
         * @param index
         * @param entry
         *
         * @throws IndexOutOfBoundsException if index is out of range
         *      <code>(index &lt; 0 || index &gt; size())</code>.
         */
        public void add(int index, IfListEntry entry) {
            super.add(index, entry);
        }

        /**
         * Returns <code>true</code> if all {@link IfListEntry} objects in the
         * list match the given token and etag. If the list is entry, it is
         * considered to match the token and etag.
         *
         * @param token The token to compare.
         * @param etag The etag to compare.
         *
         * @return <code>true</code> if all entries in the list matche the
         *      given tag and token.
         */
        public boolean match(String token, String etag) {
            log.debug("match: Trying to match token="+token+", etag="+etag);
            for (int i=0; i < size(); i++) {
                IfListEntry ile = (IfListEntry) get(i);
                if (!ile.match(token, etag)) {
                    log.debug("match: Entry "+String.valueOf(i)+"-"+ile+" does not match");
                    return false;
                }
            }
            // invariant: all entries matched

            return true;
        }
    }

    /**
     * The <code>IfHeaderInterface</code> interface abstracts away the difference of
     * tagged and untagged <em>If</em> header lists. The single method provided
     * by this interface is to check whether a request may be applied to a
     * resource with given token and etag.
     */
    private static interface IfHeaderInterface {

        /**
         * Matches the resource, token, and etag against this
         * <code>IfHeaderInterface</code> instance.
         *
         * @param resource The resource to match this instance against. This
         *      must be absolute URI of the resource as defined in Section 3
         *      (URI Syntactic Components) of RFC 2396 Uniform Resource
         *      Identifiers (URI): Generic Syntax.
         * @param token The resource's lock token to match
         * @param etag The resource's etag to match
         *
         * @return <code>true</code> if the header matches the resource with
         *      token and etag, which means that the request is applicable
         *      to the resource according to the <em>If</em> header.
         */
        public boolean matches(String resource, String token, String etag);
    }

    /**
     * The <code>IfHeaderList</code> clss implements the {@link IfHeaderInterface}
     * interface to support untagged lists of {@link IfList}s. This class
     * implements the data container for the production :
     * <pre>
         Untagged = { "(" IfList ")" } .
     * </pre>
     */
    private static class IfHeaderList extends ArrayList implements IfHeaderInterface {

        /**
         * Matches a list of {@link IfList}s against the token and etag. If any of
         * the {@link IfList}s matches, the method returns <code>true</code>.
         * On the other hand <code>false</code> is only returned if non of the
         * {@link IfList}s match.
         *
         * @param resource The resource to match, which is ignored by this
         *      implementation. A value of <code>null</code> is therefor
         *      acceptable.
         * @param token The token to compare.
         * @param etag The ETag value to compare.
         *
         * @return <code>True</code> if any of the {@link IfList}s matches the token
         *      and etag, else <code>false</code> is returned.
         */
        public boolean matches(String resource, String token, String etag) {
            log.debug("matches: Trying to match token="+token+", etag="+etag);

            for (int i=0; i < size(); i++) {
                IfList il = (IfList) get(i);
                if (il.match(token, etag)) {
                    log.debug("matches: Found match with "+il);
                    return true;
                }
            }
            // invariant: no match found

            return false;
        }
    }

    /**
     * The <code>IfHeaderMap</code> clss implements the {@link IfHeaderInterface}
     * interface to support tagged lists of {@link IfList}s. This class
     * implements the data container for the production :
     * <pre>
         Tagged = { "<" Word ">" "(" IfList ")" } .
     * </pre>
     */
    private static class IfHeaderMap extends HashMap implements IfHeaderInterface {

        /**
         * Matches the token and etag for the given resource. If the resource is
         * not mentioned in the header, a match is assumed and <code>true</code>
         * is returned in this case.
         *
         * @param resource The absolute URI of the resource for which to find
         *      a match.
         * @param token The token to compare.
         * @param etag The etag to compare.
         *
         * @return <code>true</code> if either no entry exists for the resource
         *      or if the entry for the resource matches the token and etag.
         */
        public boolean matches(String resource, String token, String etag) {
            log.debug("matches: Trying to match resource="+resource+", token="+token+","+etag);

            IfHeaderList list = (IfHeaderList) get(resource);
            if (list == null) {
                log.debug("matches: No entry for tag "+resource+", assuming match");
                return true;
            } else {
                return list.matches(resource, token, etag);
            }
        }
    }
}