# Resolver
Date: 2013-02-18

## org.simpleframework.xml.util
Class Resolver<M extends Match>

    java.lang.Object
      java.util.AbstractCollection<E>
          java.util.AbstractSet<M>
              org.simpleframework.xml.util.Resolver<M>

All Implemented Interfaces:
  java.lang.Iterable<M>, java.util.Collection<M>, java.util.Set<M>

    public class Resolver<M extends Match>

extends java.util.AbstractSet<M>

This is used to store `Match` objects, which can then be retrieved using a string by comparing that string to the pattern of the `Match` objects. Patterns consist of characters with either the '*' or '?' characters as wild characters. The '*' character is completely wild meaning that is will match nothing or a long sequence of characters. The '?' character matches a single character.

If the '?' character immediately follows the '*' character then the match is made as any sequence of characters up to the first match of the next character. For example "/*?/index.jsp" will match all files preceeded by only a single path. So "/pub/index.jsp" will match, however "/pub/bin/index.jsp" will not, as it has two paths. So, in effect the '*?' sequence will match anything or nothing up to the first occurence of the next character in the pattern.

A design goal of the `Resolver` was to make it capable of high performance. In order to achieve a high performance the `Resolver` can cache the resolutions it makes so that if the same text is given to the `Resolver.resolve` method a cached result can be retrived quickly which will decrease the length of time and work required to perform the match.

The semantics of the resolver are such that the last pattern added with a wild string is the first one checked for a match. This means that if a sequence of insertions like `add(x)` followed by `add(y)` is made, then a `resolve(z)` will result in a comparison to y first and then x, if z matches y then it is given as the result and if z does not match y and matches x then x is returned, remember if z matches both x and y then y will be the result due to the fact that is was the last pattern added.

Author:
  Niall Gallagher

Field Summary
`protected org.simpleframework.xml.util.Resolver.Cache` `cache` Caches the text resolutions made to reduce the work required.
`protected org.simpleframework.xml.util.Resolver.Stack` `stack` Stores the matches added to the resolver in resolution order.

Constructor Summary
`Resolver()` The default constructor will create a `Resolver` without a large cache size.

Method Summary
`boolean` `add(M match)` This inserts the `Match` implementation into the set so that it can be used for resolutions.
`void` `clear()` This is used to clear all matches from the set.
`java.util.Iterator<M>` `iterator()` This returns an `Iterator` that iterates over the matches in insertion order.
`boolean` `remove(M match)` This is used to remove the `Match` implementation from the resolver.
`M` `resolve(java.lang.String text)` This will search the patterns in this `Resolver` to see if there is a pattern in it that matches the string given.
`java.util.List<M>` `resolveAll(java.lang.String text)` This will search the patterns in this `Resolver` to see if there is a pattern in it that matches the string given.
`int` `size()` Returns the number of matches that have been inserted into the `Resolver`.

Methods inherited from class java.util.AbstractSet
`equals, hashCode, removeAll`

Methods inherited from class java.util.AbstractCollection
`addAll, contains, containsAll, isEmpty, remove, retainAll, toArray, toArray, toString`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Methods inherited from interface java.util.Set
`addAll, contains, containsAll, isEmpty, remove, retainAll, toArray, toArray`

Field Detail

### cache

    protected final org.simpleframework.xml.util.Resolver.Cache cache

  Caches the text resolutions made to reduce the work required.

### stack

    protected final org.simpleframework.xml.util.Resolver.Stack stack

  Stores the matches added to the resolver in resolution order.

Constructor Detail

### Resolver

    public Resolver()

  The default constructor will create a `Resolver` without a large cache size. This is intended for use when the requests for `resolve` tend to use strings that are reasonably similar. If the strings issued to this instance are dramatically different then the cache tends to be an overhead rather than a bonus.

Method Detail

### resolve

    public M resolve(java.lang.String text)

  This will search the patterns in this `Resolver` to see if there is a pattern in it that matches the string given. This will search the patterns from the last entered pattern to the first entered. So that the last entered patterns are the most searched patterns and will resolve it first if it matches.

  Parameters:
    `text` - this is the string that is to be matched by this
  Returns:
    this will return the first match within the resolver

### resolveAll

    public java.util.List<M> resolveAll(java.lang.String text)

  This will search the patterns in this `Resolver` to see if there is a pattern in it that matches the string given. This will search the patterns from the last entered pattern to the first entered. So that the last entered patterns are the most searched patterns and will resolve it first if it matches.

  Parameters:
    `text` - this is the string that is to be matched by this
  Returns:
    this will return all of the matches within the resolver

### add

    public boolean add(M match)

  This inserts the `Match` implementation into the set so that it can be used for resolutions. The last added match is the first resolved. Because this changes the state of the resolver this clears the cache as it may affect resolutions.

  Specified by:
    `add` in interface `java.util.Collection<M extends Match>`
  Specified by:
    `add` in interface `java.util.Set<M extends Match>`
  Overrides:
    `add` in class `java.util.AbstractCollection<M extends Match>`
  Parameters:
    `match` - this is the match that is to be inserted to this
  Returns:
    returns true if the addition succeeded, always true

### iterator

    public java.util.Iterator<M> iterator()

  This returns an `Iterator` that iterates over the matches in insertion order. So the first match added is the first retrieved from the `Iterator`. This order is used to ensure that resolver can be serialized properly.

  Specified by:
    `iterator` in interface `java.lang.Iterable<M extends Match>`
  Specified by:
    `iterator` in interface `java.util.Collection<M extends Match>`
  Specified by:
    `iterator` in interface `java.util.Set<M extends Match>`
  Specified by:
    `iterator` in class `java.util.AbstractCollection<M extends Match>`
  Returns:
    returns an iterator for the sequence of insertion

### remove

    public boolean remove(M match)

  This is used to remove the `Match` implementation from the resolver. This clears the cache as the removal of a match may affect the resoultions existing in the cache. The `equals` method of the match must be implemented.

  Parameters:
    `match` - this is the match that is to be removed
  Returns:
    true of the removal of the match was successful

### size

    public int size()

  Returns the number of matches that have been inserted into the `Resolver`. Although this is a set, it does not mean that matches cannot used the same pattern string.

  Specified by:
    `size` in interface `java.util.Collection<M extends Match>`
  Specified by:
    `size` in interface `java.util.Set<M extends Match>`
  Specified by:
    `size` in class `java.util.AbstractCollection<M extends Match>`
  Returns:
    this returns the number of matches within the set

### clear

    public void clear()

  This is used to clear all matches from the set. This ensures that the resolver contains no matches and that the resolution cache is cleared. This is used to that the set can be reused and have new pattern matches inserted into it for resolution.

  Specified by:
    `clear` in interface `java.util.Collection<M extends Match>`
  Specified by:
    `clear` in interface `java.util.Set<M extends Match>`
  Overrides:
    `clear` in class `java.util.AbstractCollection<M extends Match>`