...
...
Introductions to Adaptors can be found on the Introduction to YOUnite page and the Adaptors page.
Managing adaptors can be found on the Managing Adaptors page.
The YOUnite API Documentation can be found at https://younite.us/api
What is a YOUnite Adaptor
YOUnite Adaptors are essentially extensions to the YOUnite DataHub allowing access to where managed data is delivered to and retrieved from. 3rd parties implement these adaptors using the YOUnite Adaptor SDK. They can represent federated as well as centralized data depending on the implementation dynamics.
...
For more information on YOUnite adaptors see:
...
Introductions to Adaptors can be found on the Introduction to YOUnite
...
page and the Adaptors page.
Managing adaptors can be found on the Managing Adaptors page.
The YOUnite API Documentation can be found at https://younite.us/api
...
How to Get Started
An Adaptor is implemented using the YOUnite Adaptor SDK. The SDK takes care of quite a bit of the complexity behind the scenes, but there are still a few things developers will need to be aware of... namely some configuration elements, the life cycle, and the proper use of the SDK Annotations.
...
Once you have these configured in your project POM, the YOUnite Adaptor SDK will be available for you to get started with.
Dependencies
The YOUnite Adaptor SDK aims to be a very small, easy to use library. As such, it has been part of the design goal to avoid depending on external libraries as much as possible. But sometimes, it is better to use well designed and tested libraries to perform menial work than attempting to roll your own. As such, the YOUnite Adaptor SDK depends on only a few libraries so as to have a minimal impact on integrating within existing applications that may use the same libraries, possibly of different versions. The first of these dependencies is the Google Reflections library. This library provides runtime reflection capabilities needed to find and resolve classes and methods. The second library is the Jackson YAML processor. This is used primarily to support the YAML configuration file format, if selected.
...
| Code Block |
|---|
<dependency>
<groupId>org.reflections</groupId>
<artifactId>reflections</artifactId>
<!-- use latest version of Reflections -->
<version>0.9.11</version>
</dependency>
<!-- Jackson YAML Databind -->
<dependency>
<groupId>com.fasterxml.jackson.dataformat</groupId>
<artifactId>jackson-dataformat-yaml</artifactId>
<version>${jackson.version}</version>
</dependency> |
Adaptor Architecture
Once an Adaptor is connected to the YOUnite DataHub through the YOUnite Message Bus, it is able to send and receive data and ops messages. However, to streamline an Adaptor Developers time, the SDK has a minimal configuration step so that developers can focus on the business logic their Adaptor is being built for and not the inner workings of sending and receiving messages, parsing those messages, and so on. To facilitate this, the YOUnite Adaptor SDK makes use of annotations developers use to define the capabilities related to the data their Adaptor can produce and/or consume. These capabilities loosely translate into a Pub/Sub configuration on the YOUnite DataHub... essentially they indicate to the YOUnite DataHub the specific Domain properties they are interested in receiving changes for, and which of their own Domain properties they will push out to the YOUnite DataHub when a change occurs within the associated local service(s) the Adaptor is implemented to work with. These local services could be direct database data, an FTP server, in-memory data, or a remote service with data. In fact, the dynamic nature of YOUnite Domains leave the details to individual Adaptor implementations to determine how they access the domain property data to send and/or what to do with incoming domain property data.
Connecting Adaptors to the YOUnite DataHub
To get connected to the YOUnite DataHub, an Adaptor must make use of a dynamic transport layer. Out of the box, YOUnite is integrated with the Active MQ Message Bus as the transport layer. Regardless of the actual underlying transport layer, the YOUnite Adaptor SDK shields the Adaptor developer from having to be concerned with any of the details on how to connect, send and receive data via the transport layer. The YOUnite Adaptor SDK comes bundled with an implementation of the AMQ Transport layer, so nothing more is needed to be done with regards to this to get started, except for some configuration details which are described next.
...
Configuring
Because the YOUnite DataHub Runtime Engine may be deployed in any number of environments (including but not limited to local developer machines, QA, Staging, Production..), it is necessary to instruct the YOUnite Adaptor SDK on how to connect to the YOUnite DataHub. Specifically, the URL that the YOUnite Adaptor SDK will use to connect to the implemented transport layer, authentication details which allow the transport layer to identify the specific Adaptor to the YOUnite DataHub as a legitimate Adaptor, a valid Adaptor UUID and Zone UUID (previously registered with the YOUnite DataHub) and possibly the OAUTH Server URL used by the transport layer... (TODO: Determine if this is necessary.. or can the transport layer which is already configured with the URL details in order to check the validity of the adaptor authentication just use what it has configured).
There are two ways in which an Adaptor can be configured. One is to use a YAML configuration file that is provided to the YOUnite Adaptor SDK in the init() method. The other is to create a Config object, provided by the SDK, and fill in the variety of configuration properties, such as those mentioned previously and a few others. The YAML file is turned in to a Config object when that is the configuration option used. Either way is identical to the SDK, though providing a YAML file can present some potential runtime issues if the file is not valid, or not found, etc. On the other hand, it does allow for an external configuration file as opposed to code that has to be recompiled to pick up any configuration changes.
...
Startup
Once you have everything configured, you simply call the AdaptorSDK.init() method. You pass it either the Config object, or the file location of the YAML configuration file. <Add links to example working code here>. This will take the configuration, attach to the transport layer, authenticate and if all goes well, set up data and ops listeners for incoming messages. Behind the scenes, the YOUnite Adaptor SDK attempts to locate any annotated adaptor classes, build the capabilities list from annotated methods within adaptor classes, connect to the transport layer, send the capabilities list to the YOUnite DataHub and build some necessary mappings in memory for the SDK to properly process incoming messages.
Mappings
...
Internally the YOUnite Adaptor SDK maintains some data structures to keep track of the capabilities of the adaptor, and the associated domain version(s) of the YOUnite DataHub. This is what makes it possible to respond to incoming data, as well as send outgoing data do to some form of data change detection that the adaptor developer implements, which will all become clear in the next few sections... but first, adaptor capabilities and how they are defined.
Adaptor Capabilities
As mentioned previously, when an adaptor is started (the AdaptorSDK.init() method is called), it builds the list of capabilities that it needs to send to the YOUnite DataHub so the DataHub knows what data the adaptor accepts (most notably from other adaptors), as well as what data the adaptor can provide (most notably to other adaptors). But what are these capabilities, and how do you define them?
...
In the above, you can see how both domains are accounted for in separate methods but in just the one Adaptor. You can specify as many of these as you want in one class, though to keep code clean it would be best to follow this practice only when you may need to utilize multiple domains in the one class.
What is a
...
Capability Then?
Simple.. a capability is nothing more than a domain name, version and a subset of properties defined by the Domain Schema, declared in one of the Action annotations. For each action annotation defined, at least one domain name and version are specified (remember.. no point in defining an action without the domain name and version it expects to work with.. it is an error otherwise). Each and every @Domain() becomes a capability.
Same Domain,
...
Different Properties
It is possible to use the same action annotation multiple times on different methods. This allows the Adaptor Developer to separate theri code by domain/version, if they wish, or.. you can even separate individual properties on a property per method basis, if you are so inclined. For example:
...
In the above, you can see that the same action is used on two methods for the same domain and version. However, the property is different for each. One returns the Student with the name filled out, the other returns the Student with the address filled out. You may have noticed they both return a Student object.. yet they define different properties. So what is to stop an adaptor developer from filling in other properties in either of the Student objects other than the property(ies) it is declared to manage? Nothing. Yup.. nothing. Any extra data will simply be ignored by the DataHub <TODO: We MIGHT remove data before it is sent at the SDK layer.. not initially..but in a future version, scrub data not defined so as to avoid the DataHub having to do that work (e.g. distribute the load of doing that work to the adaptors to limit the processing needed by DataHub for this menial task). > Lets be clear though.. the purpose for specifying the same action for domain/version but different properties is code aesthetics. So.. an adaptor developer that tries to shoehorn extra data in to the object is being a bad citizen. Dont do it. Keep the code concise and consistent.
Combining
...
Capabilities
In the previous section, you saw that you could define the same action for the same domain and version, but declare different properties. You also learned that a capability is nothing more than the domain name and version and its properties. So what happens when you have two (or more) methods with the same action annotation each having a subset of the domain schema properties? They get combined in to one capability. A capability is the domain name/version and the sum of all properties defined, regardless of the number of methods the definitions are distributed over.
What
...
About Flowing into adaptors from YOUnite?
There are actions to handle those situations too. There is PostOrLinkToAdaptor, and PutToAdaptor, as well as DeleteAtAdaptor. PostOrLinkToAdaptor would be used when new data is to be stored at the local service. Typically this would mean the entire domain object is provided as the parameter to the method that is annotated with PostOrLinkToAdaptor. Data changes to individual properties, on the other hand, would fall under the PutToAdaptor action. This is used to update (think overwrite) the local data with what is provided from the DataHub.
...