In this post, I am going to present an example of Service Encapsulation using the case study of ACME Social and the University of Nowhere that is described in the linked article.
Service Encapsulation is often used to hide the internal representation, or state, of an object from the outside. In this way, we can present to the outside world a cleaner, simpler, and more coherent view of the internal systems. Many services which were not initially planned for a Service Oriented Architecture (SOA) may get encapsulated or become a part of a SOA in this way.
In the example of ACME Social and University of Nowhere, both the parties agreed on exchanging information in order to improve the existing geolocation service of ACME Social. In particular, ACME Social would like to receive the following information from the University of Nowhere:
- Retrieve a list of unique IDs of the students
- Retrieve the email addresse(s) of each student
- Get the class that the student is supposed to follow
- Retrieving the exact coordinates of the location of a given student according to the University of Nowhere.
Service Encapsulation: Can we design it as a stateless service?
Probably yes, even though students and their respective locations will change. From the point of view of the methods, we can expect that their behavior will not change over time. A possible UML diagram that describes the interface of the service could be as follows:
The class represents all the functionalities requested by ACME Social in 4 methods. It does not have attributes and this approach will keep the design simple. IDs, emails, as well as geocoordinates will be shared as Strings in order to use one of the basic types of a service.
In the case we will decide to implement a WS-I compliant service, we can assume that the calls of the methods can fail and may trigger exceptions on the service consumer’s side.
What about the concerns of ACME Social and the documentation of the service?
As the service represents the entry point of the systems of the university of Nowhere, we need to carefully balance the complexity of the interface that we need to design. On the one hand, it must be able to mask all the idiosyncrasies of the IT of the university in order to facilitate its consumption by ACME Social. On the other hand it must be able to deliver everything that is needed and agreed. The figure below shows how this interface sits at the intersection points of two different worlds with different needs and goals:
ACME Social, i.e. the client of the service needs a clear answer to the following questions:
- What does the service do? Answering to this question will require a proper documentation of the methods. The name may be intuitive, but some of its behavior may not. Therefore, it needs to be carefully documented.
- How can we use the service? The best way to answer this question is with an example of use. ACME social may use different languages so the example(s) need to be written in Java and Python (for example) and the code must be well documented (see these best practices).
- Where can we locate the service? The URL of the service, together with the way to get the authorization of use, should be part of the documentation. In addition, the service should be part of an UDDI registry as well.
ACME Social is not at all interested in:
- How to represent internally the request received from ACME social
- How to implement the service
- Where to host the server needed for running the service
- How to publish the service in the Internet
- How to keep it running
These aspects are of fundamental importance for the University of Nowhere. However, these concerns should not be shared with the consumers of the service.
A #service Encapsulation example using a location service. #servicedesign #programming
Click To Tweet
