Status

Current state: "Draft"

Discussion thread: https://lists.apache.org/thread/3qppq1nks6vwf6m5lljbw9nmofb90lbp

...

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast). Confluence supports inline comments that can also be used.

Motivation

Solr's omnipresent NamedList (not SimpleOrderedMap) holds the project back from better JSON compatibility, and use of a standard Java Map abstraction.  Why is this?:

...

While there is a special and important subclass of NamedList named "SimpleOrderedMap", all references to NamedList here mean the implementing type NamedList and not SimpleOrderedMap.

Public Interfaces

SolrResponse.getResponse,

...

getResponseHeader,

...

NamedListInitializedPlugin.init,

...

...more
  – but many more; really it's nearly all public methods with NamedList in the signature.

Several Options; pick one:

...

(B) use SimpleOrderedMap.  A small upgrade hassle but otherwise it's business as usual.  No rush to update any code.  Lots of Solr code will experience a one-liner change.  Minor grumble:  IMO the name is clumsy and suddenly will be rather omnipresent.

(C) use Map, with SimpleOrderedMap being a typical but not mandatory implementation.  To help transition, a static utility method on SimpleOrderedMap can cast or convert a Map to a SimpleOrderedMap for code still using a NamedList.  Note that NamedList implements NavigableObject, which has useful utility methods to extract data from nested structures, especially in tests.  The switch to Map (isn't NavigableObject) may mean wanting to make SolrResponse implement NavigableObject or other tweaks to retain succinct calls.

Proposed Changes

(should be done in this order, mostly, and with one Jira per step unless specified otherwise)

SimpleOrderedMap (the subclass of NamedList) shall actually implement Map.  Backported to 9x.  

"javabin" encoding shall decode all map data as a SimpleOrderedMap (vs. say a LinkedHashMap) thus allowing "javabin" consumers to compatibility read a SimpleOrderedMap or Map without differentiation to the calling code casting as one or the other.  Even SimpleOrderedMap is a NamedList, thus the calling code might cast to that type.  This should be configurable, particularly for Solr 9.9.  If "javabin" is retained even longer term (not yet replaced with CBOR or...), this decision might be reversed as we reduce casts to NamedList/SimpleOrderedMap, instead preferring Map.

...

Solr shall read configuration at a plugin root level (e.g. for PluginInfo from ConfigNode from solrconfig.xml) as a SimpleOrderedMap (not NamedList), with new enforcement of unique keys here (not for SimpleOrderedMap generally).  Plugins that use repeated keys will need to change their configuration strategy, like to use an array.  This will not change interpreting "lst" in XML Solr configuration as anything different, as those elements are nested, not at root configurables (e.g. not for requestHandler or queryParser or...).

Compatibility, Deprecation, and Migration Plan

• What impact (if any) will there be on existing users?
• If we are changing behavior how will we phase out the older behavior?
• If we need special migration tools, describe them here.
• When will we remove the existing behavior?

Test Plan

Describe in few sentences how the SIP will be tested. We are mostly interested in system tests (since unit-tests are specific to implementation details). How will we know that the implementation works as expected? How will we know nothing broke?

Rejected Alternatives

• Primary changes are Solr 10.  Some aspects affect plugin compatibility.  Some aspects affect javabin and/or jSON compatibility.

Test Plan

Solr doesn't have backwards-compatibility tests; we should have someIf there are alternative ways of accomplishing the same thing, what were they? The purpose of this section is to motivate why the design is the way it is and not some other way.