IfHeader class represents the state lists defined through the HTTP If header, which is
* specified in RFC 2518 as follows :
*
*
* If = "If" ":" ( 1*No-tag-list | 1*Tagged-list)
* No-tag-list = List
* Tagged-list = Resource 1*List
* Resource = Coded-URL
* List = "(" 1*(["Not"](State-etag | "[" entity-tag "]")) ")"
* State-etag = Coded-URL
* Coded-URL = "<" absoluteURI ">"
*
* * Reformulating this specification into proper EBNF as specified by N. Wirth we get the following productions, which * map to the parse METHODS of this class. Any whitespace is ignored except for white space surrounding and within words * which is considered significant. * *
* If = "If:" ( Tagged | Untagged ).
* Tagged = { "<" Word ">" Untagged } .
* Untagged = { "(" IfList ")" } .
* IfList = { [ "Not" ] ( ("<" Word ">" ) | ( "[" Word "]" ) ) } .
* Word = characters .
*
* * An If header either contains untagged IfList entries or tagged IfList entries but not a * mixture of both. An If header containing tagged entries is said to be of tagged type while an * If header containing untagged entries is said to be of untagged type. *
* An IfList is a list of tokens - words enclosed in < > - and etags - words enclosed in [ * ]. An IfList matches a (token, etag) tuple if all entries in the list match. If an entry in the list is * prefixed with the word Not (parsed case insensitively) the entry must not match the concrete token or etag. *
* Example: The ifList (<token> [etag]) only matches if the concrete token has the value
* token and the concrete etag has the value etag. On the other hand, the ifList
* (Not <notoken>) matches any token which is not notoken (in this case the concrete
* value of the etag is not taken into consideration).
*
* This class was contributed by Apache Jackrabbit
*
* @author Felix Meschberger
*/
public class WebdavIfHeader {
private static final Log log = LogFactory.getLog(WebdavIfHeader.class);
private static final StringManager sm = StringManager.getManager(WebdavIfHeader.class.getPackage().getName());
/**
* The string representation of the header value
*/
private final String headerValue;
/**
* The list of untagged state entries
*/
private final IfHeaderInterface ifHeader;
/**
* The list of resources present in the If header.
*/
private final List
* If the If header is of untagged type, the untagged IfList is matched against the token and etag
* given: A match of the token and etag is found if at least one of the IfList entries match the token and
* etag tuple.
*
* @param tag The tag to identify the IfList to match the token and etag against.
* @param tokens The tokens to compare.
* @param etag The ETag value to compare.
*
* @return If the If header is of untagged type the result is
* Note that this method does not support any escaping.
*
* @param reader The
* This helper method can be called by implementations to evaluate the concrete match on the correct value
* parameter. See {@link #match(String, String)} for the external API method.
*
* @param value The string value to compare to the {@link #value} field.
*
* @return
* Implementing METHODS may call the helper method {@link #match(String)} for the actual matching.
*
* @param token The token value to compare
* @param etag The etag value to compare
*
* @return
* This class is a container for data contained in the If production IfList
*
*
*/
private static class IfList extends ArrayListIfHeader if the given lock tokens.
*
* @param tokens the tokens
*
* @throws IOException If the parsing of the IfHeader fails
*/
public WebdavIfHeader(String[] tokens) throws IOException {
allTokens.addAll(Arrays.asList(tokens));
StringBuilder b = new StringBuilder();
for (String token : tokens) {
b.append("(").append("<");
b.append(token);
b.append(">").append(")");
}
headerValue = b.toString();
ifHeader = parse();
}
/**
* Parses the If header and creates and internal representation which is easy to query.
*
* @param uriPrefix The uri prefix to use for the absolute href
* @param ifHeaderValue the if header
*
* @throws IOException If the parsing of the IfHeader fails
*/
public WebdavIfHeader(String uriPrefix, String ifHeaderValue) throws IOException {
this.uriPrefix = uriPrefix;
headerValue = ifHeaderValue;
ifHeader = parse();
}
/**
* @return If String.
*/
public String getHeaderName() {
return "If";
}
/**
* Return the String representation of the If header present on the given request or null.
*
* @return If header value as String or null.
*/
public String getHeaderValue() {
return headerValue;
}
/**
* Returns true if an If header was present in the given request. False otherwise.
*
* @return true if an If header was present.
*/
public boolean hasValue() {
return ifHeader != null;
}
/**
* Tries to match the contents of the If header with the given token and etag values with the restriction
* to only check for the tag.
* true if any of the
* IfList entries matches the token and etag values. For tagged type If header the
* result is true if either no entry for the given tag exists in the If header or
* if the IfList for the given tag matches the token and etag given.
*/
public boolean matches(String tag, List
* Tagged = { "<" Word ">" Untagged } .
*
*
* @param reader the reader
*
* @return the parsed map
*/
private IfHeaderMap parseTagged(StringReader reader) throws IOException {
IfHeaderMap map = new IfHeaderMap();
while (true) {
// read next non-white space
int c = readWhiteSpace(reader);
if (c < 0) {
// end of input, no more entries
break;
} else if (c == '<') {
// start a tag with an IfList
String resource = readWord(reader, '>');
if (resource != null) {
// go to untagged after reading the resource
map.put(resource, parseUntagged(reader));
resources.add(resource);
} else {
break;
}
} else {
// unexpected character
// catchup to end of input or start of a tag
logIllegalState("Tagged", c, "<", reader);
}
}
return map;
}
/**
* Parses an untagged type If header. This method implements the Untagged production given in the
* class comment :
*
*
* Untagged = { "(" IfList ")" } .
*
*
* @param reader The StringReader to read from for parsing
*
* @return An ArrayList of {@link IfList} entries.
*/
private IfHeaderList parseUntagged(StringReader reader) throws IOException {
IfHeaderList list = new IfHeaderList();
while (true) {
// read next non whitespace
reader.mark(1);
int c = readWhiteSpace(reader);
if (c < 0) {
// end of input, no more IfLists
break;
} else if (c == '(') {
// start of an IfList, parse
list.add(parseIfList(reader));
} else if (c == '<') {
// start of a tag, return current list
reader.reset();
break;
} else {
// unexpected character
// catchup to end of input or start of an IfList
logIllegalState("Untagged", c, "(", reader);
}
}
return list;
}
/**
* Parses an IfList in the If header. This method implements the Tagged production given
* in the class comment :
*
*
* IfList = { [ "Not" ] ( ("<" Word ">" ) | ( "[" Word "]" ) ) } .
*
*
* @param reader The StringReader to read from for parsing
*
* @return The {@link IfList} for the input IfList.
*
* @throws IOException if a problem occurs during reading.
*/
private IfList parseIfList(StringReader reader) throws IOException {
IfList res = new IfList();
boolean positive = true;
String word;
ReadLoop:
while (true) {
int nextChar = readWhiteSpace(reader);
switch (nextChar) {
case 'N':
case 'n':
// read not
// check whether o or O
int not = reader.read();
if (not != 'o' && not != 'O') {
logIllegalState("IfList-Not", not, "o", null);
break;
}
// check whether t or T
not = reader.read();
if (not != 't' && not != 'T') {
logIllegalState("IfList-Not", not, "t", null);
break;
}
// read Not ok
positive = false;
break;
case '<':
// state token
word = readWord(reader, '>');
if (word != null) {
res.add(new IfListEntryToken(word, positive));
// also add the token to the list of all tokens
if (positive) {
allTokens.add(word);
} else {
allNotTokens.add(word);
}
positive = true;
}
break;
case '[':
// etag
word = readWord(reader, ']');
if (word != null) {
res.add(new IfListEntryEtag(word, positive));
positive = true;
}
break;
case ')':
// correct end of list, end the loop
if (log.isTraceEnabled()) {
log.trace("parseIfList: End of If list, terminating loop");
}
break ReadLoop;
default:
logIllegalState("IfList", nextChar, "nN<[)", reader);
// abort loop if EOF
if (nextChar < 0) {
break ReadLoop;
}
break;
}
}
// return the current list anyway
return res;
}
/**
* Returns the first non-whitespace character from the reader or -1 if the end of the reader is encountered.
*
* @param reader The Reader to read from
*
* @return The first non-whitespace character or -1 in case of EOF.
*
* @throws IOException if a problem occurs during reading.
*/
private int readWhiteSpace(Reader reader) throws IOException {
int c = reader.read();
while (c >= 0 && Character.isWhitespace((char) c)) {
c = reader.read();
}
return c;
}
/**
* Reads from the input until the end character is encountered and returns the string up to but not including this
* end character. If the end of input is reached before reading the end character null is returned.
* Reader to read from
* @param end The ending character limiting the word.
*
* @return The string read up to but not including the ending character or null if the end of input is
* reached before the ending character has been read.
*
* @throws IOException if a problem occurs during reading.
*/
private String readWord(Reader reader, char end) throws IOException {
StringBuilder buf = new StringBuilder();
// read the word value
int c = reader.read();
for (; c >= 0 && c != end; c = reader.read()) {
buf.append((char) c);
}
// check whether we succeeded
if (c < 0) {
log.error("readWord: Unexpected end of input reading word");
return null;
}
// build the string and return it
return buf.toString();
}
/**
* Logs an unexpected character with the corresponding state and list of expected characters. If the reader
* parameter is not null, characters are read until either the end of the input is reached or any of the characters
* in the expChar string is read.
*
* @param state The name of the current parse state. This method logs this name in the message. The intended value
* would probably be the name of the EBNF production during which the error occurs.
* @param effChar The effective character read.
* @param expChar The list of characters acceptable in the current state.
* @param reader The reader to be caught up to any of the expected characters. If null the input is
* not caught up to any of the expected characters (of course ;-).
*/
private void logIllegalState(String state, int effChar, String expChar, StringReader reader) {
// format the effective character to be logged
String effString = (effChar < 0) ? "IfListEntry abstract class is the base class for entries in an IfList production. This
* abstract base class provides common functionality to both types of entries, namely tokens enclosed in angle
* brackets (< >) and etags enclosed in square brackets ([ ]).
*/
private abstract static class IfListEntry {
/**
* The entry string value - the semantics of this value depends on the implementing class.
*/
protected final String value;
/** Flag to indicate, whether this is a positive match or not */
protected final boolean positive;
/** The cached result of the {@link #toString} method. */
protected String stringValue;
/**
* Sets up the final fields of this abstract class. The meaning of value parameter depends solely on the
* implementing class. From the point of view of this abstract class, it is simply a string value.
*
* @param value The string value of this instance
* @param positive true if matches are positive
*/
protected IfListEntry(String value, boolean positive) {
this.value = value;
this.positive = positive;
}
/**
* Matches the value from the parameter to the internal string value. If the parameter and the {@link #value}
* field match, the method returns true for positive matches and false for negative
* matches.
* true if the value parameter and the {@link #value} field match and the {@link #positive}
* field is true or if the values do not match and the {@link #positive} field is
* false.
*/
protected boolean match(String value) {
return positive == this.value.equals(value);
}
/**
* Matches the entry's value to the token or etag. Depending on the concrete implementation, only one of the
* parameters may be evaluated while the other may be ignored.
* true if the token/etag matches the IfList entry.
*/
public abstract boolean match(String token, String etag);
/**
* Returns a short type name for the implementation. This method is used by the {@link #toString} method to
* build the string representation if the instance.
*
* @return The type name of the implementation.
*/
protected abstract String getType();
/**
* @return the value of this entry
*/
protected String getValue() {
return value;
}
/**
* Returns the String representation of this entry. This method uses the {@link #getType} to build the string
* representation.
*
* @return the String representation of this entry.
*/
@Override
public String toString() {
if (stringValue == null) {
stringValue = getType() + ": " + (positive ? "" : "!") + getValue();
}
return stringValue;
}
}
/**
* The IfListEntryToken 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 true 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 true if the values match and
* if the match is positive. true 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 true if the token matches the IfList entry's token value.
*/
@Override
public boolean match(String token, String etag) {
return token == null || super.match(token);
}
/**
* Returns the type name of this implementation, which is fixed to be Token.
*
* @return The fixed string Token as the type name.
*/
@Override
protected String getType() {
return "Token";
}
}
/**
* The IfListEntryToken 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 true 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 true if the values match and if
* the match is positive. true 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 true if the etag matches the IfList entry's etag value.
*/
@Override
public boolean match(String token, String etag) {
return super.match(etag);
}
/**
* Returns the type name of this implementation, which is fixed to be ETag.
*
* @return The fixed string ETag as the type name.
*/
@Override
protected String getType() {
return "ETag";
}
}
/**
* The IfList class extends the ArrayList class with the limitation to only support adding
* {@link IfListEntry} objects and adding a {@link #match} method.
*
* IfList = { [ "Not" ] ( ("<" Word ">" ) | ( "[" Word "]" ) ) } .
*
* true (as per the general contract of Collection.add).
*/
@Override
public boolean add(IfListEntry entry) {
return super.add(entry);
}
/**
* Adds the {@link IfListEntry} at the indicated position of the list.
*
* @param index the index
* @param entry the entry
*
* @throws IndexOutOfBoundsException if index is out of range (index < 0 || index > size()).
*/
@Override
public void add(int index, IfListEntry entry) {
super.add(index, entry);
}
/**
* Returns true 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 tokens The token to compare.
* @param etag The etag to compare.
*
* @return true if all entries in the list match the given tag and token.
*/
public boolean match(ListIfHeaderInterface interface abstracts away the difference of tagged and untagged If
* 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 interface IfHeaderInterface {
/**
* Matches the resource, token, and etag against this IfHeaderInterface 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 tokens The resource's lock token to match
* @param etag The resource's etag to match
*
* @return true if the header matches the resource with token and etag, which means that the
* request is applicable to the resource according to the If header.
*/
boolean matches(String resource, ListIfHeaderList class implements the {@link IfHeaderInterface} interface to support untagged lists
* of {@link IfList}s. This class implements the data container for the production :
*
*
* Untagged = { "(" IfList ")" } .
*
*/
private static class IfHeaderList extends ArrayListtrue. On the other hand false is only returned if none of the
* {@link IfList}s match.
*
* @param resource The resource to match, which is ignored by this implementation. A value of null
* is therefor acceptable.
* @param tokens The tokens to compare.
* @param etag The ETag value to compare.
*
* @return True if any of the {@link IfList}s matches the token and etag, else false
* is returned.
*/
@Override
public boolean matches(String resource, ListIfHeaderMap class implements the {@link IfHeaderInterface} interface to support tagged lists of
* {@link IfList}s. This class implements the data container for the production :
*
*
* Tagged = { "<" Word ">" "(" IfList ")" } .
*
*/
private class IfHeaderMap extends HashMaptrue is returned in this case.
*
* @param resource The absolute URI of the resource for which to find a match.
* @param tokens The tokens to compare.
* @param etag The etag to compare.
*
* @return true if either no entry exists for the resource or if the entry for the resource matches
* the token and etag.
*/
@Override
public boolean matches(String resource, List