Design Approach
| Prev: Introduction | Next: Overall |
The vast amount of information to be captured and settled for designing ODataJClient needs an adequate tool for purpose, e.g. something to achieve the following objectives:
- collect, explore and re-organize basic protocol concepts;
- collect, explore and re-organize non-functional requirements;
- provide an effective way to access the protocol concepts and their relationships with main implementation concepts. Experience suggests to use a mind map, a diagram used to outline information. A mind map is often created around a single word to which associated concepts are added. Major categories radiate from a central node and lesser categories are sub-branches of larger branches.
The mind map used in the following was authored using FreeMind, multi-platform tool available for free download, and is available as FreeMind or SVG.
The first step is to visually outline main categories about protocol and implementation concepts:
The second step it to start to explore and organize acquired basic protocol concepts:
This step is really important: it has to be done in order to have an easy and efficient way to access to the information at design/implementation time. Particular care must be taken when specifying the relationships among protocol concepts and between protocol and implementation concepts as well.
The last step is to start organizing implementation ideas (right-end) by taking care to map them with protocol concepts (left-end): the figure below shows some first design and implementation tips.
The mind map produced till now will evolve during design and possibly implementation phase. In the future, figures above won't be kept synchronized with the actual map but it will be always available as separate file.
Some principles are presented below that are to bear in mind during the design process, influencing several aspects of the final work.
One of main ODataJClient targets is to become widely accepted and used by Java professionals: adherence to featured Java (and Open Source) best practices is of fundamental importance.
WCF Data Services for OData V3 is the reference implementation for .NET framework server and client libraries: keeping an eye on the related documentation could improve the global quality and speed-up the implementation of ODataJClient. In case of conflict with indications from 2.1.1, however, those should generally prevail.
ODataJClient will enable adopters to operate at two different levels:
- Protocol level (Engine)
Classes and methods will be provided that corresponds to OData requests and responses, manipulating OData payload entities; Java applications will be able to explicitly implement any OData interaction, without any abstraction on the entities manipulated nor on the operations invoked. - Mapping level (Proxy)
It will be possible to map – either via XML or Java annotations - OData entities to Java objects (POJO), OData operations to Java interfaces; once mapped, entities will also benefit of context-based state tracking. This will bring high-level, natural conversation with OData services.
While this is a very general design principle, it is specifically addressed here to highlight that ODataJClient needs to be easy to understand and put at work for beginners but also powerful enough to not enforce any unneeded restriction or limitation for advanced usage.
Do not assume that all interactions occur synchronously.
Do not fail unless fatal errors occur.
Do not rely upon any third-part library that is not working on some of the platforms to be supported.
Make as much as possible of ODataJClient configurable, ranging from metadata client-side extension to automatic retry on failure.
In OData, relationships are used to navigate from an entity to related entities: it is important to model such navigation in the most effective and handful way.
The inherent complexity of OData 3.0, alongside with the necessity to adhere to principles set above will result in an iterative design process, possibly very linked to actual implementation. For there reasons, the design artifacts will be mainly constituted by Javadoc HTML documents, dynamically generated from Java interfaces and stub classes.
| Prev: Introduction | Next: Overall |