Skip to content

GSIP 156

Torben Barsballe edited this page Feb 10, 2017 · 5 revisions

GSIP 156 - Upgrade to Jettison 1.2

Overview

Proposal to upgrade the JSON library used by the REST configuration module from jettison 1.0.1 to jettison 1.2.

Proposed By

Torben Barsballe

Assigned to Release

This proposal is for GeoServer 2.11-beta.

State

  • Under Discussion
  • In Progress
  • Completed
  • Rejected
  • Deferred

Upgrade deferred to the March 2017 Code-sprint.

Motivation

To fix JSON encoding bugs resulting in invalid JSON, caused by errors in the Jettison 1.0.1 library

Proposal

The GeoServer REST configuration module delegates from XStream to the Jettison library to encode JSON responses. Jettison 1.0.1 has known issues, some of which are fixed in Jettison 1.2. This has resulted in some errors in the REST config JSON responses, such as GEOS-7771 and GEOS-7873.

I propose to upgrade the JSON library used by the REST configuration module from jettison 1.0.1 to jettison 1.2.

This will has some additional affects on the JSON output, detailed in the Backwards Compatibility section.

Backwards Compatibility

Due to differences between Jettison 1.0.1 and 1.2, this upgrade will result in an API change to the GeoServer REST configuration JSON output format.

The change occurs when encoding lists of objects as JSON:

Example: geoserver/rest/workspaces.json:

With Jettison 1.0.1

{
    "workspaces": {
        "workspace": [
            {
                "href": "http://localhost:8080/geoserver/rest/workspaces/cite.json",
                "name": "cite"
            },
            {
                "href": "http://localhost:8080/geoserver/rest/workspaces/tiger.json",
                "name": "tiger"
            },
            {
                "href": "http://localhost:8080/geoserver/rest/workspaces/nurc.json",
                "name": "nurc"
            },
            {
                "href": "http://localhost:8080/geoserver/rest/workspaces/sde.json",
                "name": "sde"
            },
            {
                "href": "http://localhost:8080/geoserver/rest/workspaces/it.geosolutions.json",
                "name": "it.geosolutions"
            },
            {
                "href": "http://localhost:8080/geoserver/rest/workspaces/topp.json",
                "name": "topp"
            },
            {
                "href": "http://localhost:8080/geoserver/rest/workspaces/sf.json",
                "name": "sf"
            }
        ]
    }
}

With Jettison 1.2:

{
    "workspaces": [
        {
            "workspace": [
                {
                    "href": "http://localhost:8080/geoserver/rest/workspaces/sf.json",
                    "name": "sf"
                },
                {
                    "href": "http://localhost:8080/geoserver/rest/workspaces/sde.json",
                    "name": "sde"
                },
                {
                    "href": "http://localhost:8080/geoserver/rest/workspaces/cite.json",
                    "name": "cite"
                },
                {
                    "href": "http://localhost:8080/geoserver/rest/workspaces/nurc.json",
                    "name": "nurc"
                },
                {
                    "href": "http://localhost:8080/geoserver/rest/workspaces/tiger.json",
                    "name": "tiger"
                },
                {
                    "href": "http://localhost:8080/geoserver/rest/workspaces/it.geosolutions.json",
                    "name": "it.geosolutions"
                },
                {
                    "href": "http://localhost:8080/geoserver/rest/workspaces/topp.json",
                    "name": "topp"
                }
            ]
        }
    ]
}

Notice how the workspaces list object has been wrapped in a single element array: from {workspaces: { workspace: [...] } } to {workspaces: [ { workspace: [...] } ] }.

This can be better observed in the Resources REST api:

Elsewhere, single element lists are now converted to objects:

Example: REST resources geoserver/rest/resource/security/auth?format=json

Jettison 1.0.1, single-element array:

{
    "ResourceDirectory": {
        "children": {
            "child": [
                {
                    "link": {
                        "href": "http://localhost:8080/geoserver/rest/resource/security/auth/default",
                        "rel": "alternate",
                        "type": "application/json"
                    },
                    "name": "default"
                }
            ]
        },
        "lastModified": "2017-01-31 17:52:14.0 UTC",
        "name": "auth",
        "parent": {
            "link": {
                "href": "http://localhost:8080/geoserver/rest/resource/security",
                "rel": "alternate",
                "type": "application/json"
            },
            "path": "/security"
        }
    }
}

Jettison 1.2, single-element array:

{
    "ResourceDirectory": {
        "children": [
            {
                "child": {
                    "link": {
                        "href": "http://localhost:8080/geoserver/rest/resource/security/auth/default",
                        "rel": "alternate",
                        "type": "application/json"
                    },
                    "name": "default"
                }
            }
        ],
        "lastModified": "2016-11-23 20:45:44.0 UTC",
        "name": "auth",
        "parent": {
            "link": {
                "href": "http://localhost:8080/geoserver/rest/resource/security",
                "rel": "alternate",
                "type": "application/json"
            },
            "path": "/security"
        }
    }
}

Jettison 1.0.1. multi-element array:

{
    "ResourceDirectory": {
        "children": {
            "child": [
                {
                    "link": {
                        "href": "http://localhost:8080/geoserver/rest/resource/workspaces/cite",
                        "rel": "alternate",
                        "type": "application/json"
                    },
                    "name": "cite"
                },
                {
                    "link": {
                        "href": "http://localhost:8080/geoserver/rest/resource/workspaces/default.xml",
                        "rel": "alternate",
                        "type": "application/xml"
                    },
                    "name": "default.xml"
                }
            ]
        },
        "lastModified": "2017-01-18 19:02:38.0 UTC",
        "name": "workspaces",
        "parent": {
            "link": {
                "href": "http://localhost:8080/geoserver/rest/resource/",
                "rel": "alternate",
                "type": "application/json"
            },
            "path": "/"
        }
    }
}

Jettison 1.2:

{
    "ResourceDirectory": {
        "children": [
            {
                "child": [
                    {
                        "link": {
                            "href": "http://localhost:8080/geoserver/rest/resource/workspaces/cite",
                            "rel": "alternate",
                            "type": "application/json"
                        },
                        "name": "cite"
                    },
                    {
                        "link": {
                            "href": "http://localhost:8080/geoserver/rest/resource/workspaces/default.xml",
                            "rel": "alternate",
                            "type": "application/xml"
                        },
                        "name": "default.xml"
                    }
                ]
            }
        ],
        "lastModified": "2017-01-18 19:02:38.0 UTC",
        "name": "workspaces",
        "parent": {
            "link": {
                "href": "http://localhost:8080/geoserver/rest/resource/",
                "rel": "alternate",
                "type": "application/json"
            },
            "path": "/"
        }
    }
}

Observe the child element. For single-element arrays, Jetison 1.0.1 wraps the single entry in an array. With Jettison 1.2, the wrapping array is removed. For multi-element arrays, the Jettison 1.0.1 and Jettison 1.2 encodings are the same, except for the addition of the top-level array discussed above.

Note that the Jettison 1.2 encoding is probably more correct than the current Jettison 1.0.1 encoding. Neither encoding is especially good, but that is mostly a side effect of trying to output an XStream document as JSON.

Feedback

Jody: This will have to co-ordinate with the gsconfig and geoserver-manager projects, in order to protect downstream users. I do not know how sophisticated those two libraries are (do they use xml or json).

Voting

Project Steering Committee:

  • Alessio Fabiani:
  • Andrea Aime:
  • Ben Caradoc-Davies:
  • Brad Hards:
  • Christian Mueller:
  • Ian Turton:
  • Jody Garnett:
  • Jukka Rahkonen:
  • Kevin Smith:
  • Simone Giannecchini:

Links

Clone this wiki locally