Use context-specific response classes in contract with implementing projects

[scottfrederick]

The ServiceInstanceService and ServiceInstanceBindingService interfaces embody most of the contract between this project and implementing brokers. Most methods of these interfaces return the ServiceInstance and ServiceInstanceBinding objects, respectively.

In many cases, the ServiceInstanceController returns the ServiceInstance object in response to broker API calls from CC.

The over-use of the ServiceInstanceclass, and to a lesser extent the ServiceInstanceBinding class, poses several problems:

• Each call to methods of a ServiceInstanceService implementation only needs to populate a subset of fields in ServiceInstance, but it is not clear to implementing classes which fields are used in which response. Populating all fields of ServiceInstance in all ServiceInstanceService methods puts an undue burden on implementations.
• The entire ServiceInstance class is deserialized to JSON in response to CC calls that ignore most of the JSON fields.
• Some implementing brokers assume that the ServiceInstance class is intended to be used to persist service instance info in their own persistence store. Brokers often need to enhance the data contained in ServiceInstance with additional data, leading to requests to add even more fields to ServiceInfo.

I propose that the use of ServiceInstance and ServiceInstanceBinding be completely deprecated in this project. The classes can remain in the project and be marked deprecated for convenience to implementing brokers, but should not be used internally or in the contract with implementing brokers.

In place of ServiceInstance and ServiceInstanceBinding:

• The ServiceInstanceService and ServiceInstanceBindingService interfaces should return special-purpose response types. This allows the response types to contain only the fields that are necessary for the controllers to return the necessary data to CC. It also matches the current pattern of these interface methods taking special-purpose request types as parameters.
• The controllers should construct JSON responses to CC that contain only fields documented in the service broker API.
• Implementing brokers should construct their own types for persisting service instance info internally. They could continue to use ServiceInstanceService and ServiceInstanceBindingService in the near term.

[scottfrederick]

Fixed in a716a2b ea65115 c02adab