UrlEncodingService

Defines a consistent way to convert strings to/from a form safe for use within a URL.

The service is used by the framework to map mementos (derived from the state of the view model itself) into a form that can be used as a view model. When the framework needs to recreate the view model (for example to invoke an action on it), this URL is converted back into a view model memento, from which the view model can be hydrated.

API

UrlEncodingService.java
interface UrlEncodingService {
  String encode(byte[] bytes)     (1)
  byte[] decode(String str)     (2)
  String encodeString(String str)
  String decodeToString(String str)
  UrlEncodingService forTesting()     (3)
  UrlEncodingService forTestingNoCompression()     (4)
}
1 encode(byte)

Converts the string (eg view model memento) into a string safe for use within an URL
2 decode(String)

Unconverts the string from its URL form into its original form URL.
3 forTesting()

Uses base64 with compression.
4 forTestingNoCompression()

Uses base64 without compression.

Members

encode(byte)

Converts the string (eg view model memento) into a string safe for use within an URL

decode(String)

Unconverts the string from its URL form into its original form URL.

Reciprocal of #encode(byte[]) .

forTesting()

Uses base64 with compression.

forTestingNoCompression()

Uses base64 without compression.

Implementation

The framework provides a default implementation, o.a.c.core.runtimeservices.urlencoding.UrlEncodingServiceWithCompression, that first (gzip) compresses the state and then uses base-64 encoding of the resulting bytes.

Usage Notes

Defining this functionality as an SPI has two use cases:

  • first, (though some browsers support longer strings), there is a limit of 2083 characters for URLs. For view model mementos that correspond to large strings (as might occur when serializing a JAXB @XmlRootElement-annotated view model), the service provides a hook.

    For example, each memento string could be mapped to a GUID held in some cluster-aware cache.

  • the service provides the ability, to encrypt the string in order to avoid leakage of potentially sensitive state within the URL.

For large view models, there’s the possibility that the 2083 character limit could be exceeded; in such cases register an alternative implementation of this service.

See also