ObjectReader.readValues() confusing wrt whether START_ARRAY is skipped or not

[cowtowncoder]

With Jackson 1.9 and 2.0, behavior of ObjectReader.readValues() (and ObjectMapper.readValues()) is confusing, with respect to handling of case whether JsonParser points to START_ARRAY. While heuristics were added to try to support the common case, they are not well documented or necessarily even defined.

So, for 2.1, we should simplify behavior and use a two-part definition:

• For cases where JsonParser is passed as argument, no skipping is done: parser MUST either point to the first token of the first element; or not point to any token (in which case JsonParser.nextToken() will be called to point to the first token of the first element). Value of token parser points to has no effect on behavior.
• For cases where JsonParser is constructed by ObjectReader, type of the first token (of the document) is checked: if it is START_ARRAY, token will be skipped assuming that sequence is wrapped in a JSON array, and the token following is assumed to be the first token of the first element.

The benefits of this definition over earlier (2.0) functioning are:

• Allows binding of all kinds of wrapped/unwrapped sequences, regardless of JSON structures of individual elements, and their mapping to Java types.
• Simple definition; no auto-magical determination

The main downside is that functionality will not be 100% backwards compatible; this is unfortunate, but given that the definition of behavior earlier was not fully documented, earlier functioning can not be considered as correct (that is: this is a bug fix; defining formerly unspecific behavior).

[cowtowncoder]

Implemented as planned; improved Javadocs. Will be in 2.1: behavior of 1.9 and 2.0 is NOT changed, since they are patch branches and no functionality changes allowed.