Page Comparison

...

...

...

YOUnite Adaptors are essentially extensions to the YOUnite DataHub, allowing access to managed data. Third parties implement these adaptors using the YOUnite Adaptor SDK. Adaptors are a fundamental component to federated data domains.

For more information on YOUnite adaptors see:

...

Table of Contents

What is a YOUnite Adaptor

YOUnite Adaptors are essentially extensions to the YOUnite Data Hub, allowing access to managed data. Third parties implement these adaptors using the YOUnite Adaptor SDK. Adaptors are a fundamental component to federated data domains.

...

For more information on YOUnite adaptors see:

Introductions to Adaptors can be found on the Introduction to YOUnite page and the Adaptors page.

...

<dependencies>
  <dependency>
    <groupId>com.younite</groupId>
    <artifactId>adaptor-sdk</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </dependency>
</dependencies>

3. Add a server to your project POM to access the YOUnite Maven Repository: <TODO KEVIN: ONCE YOUNITE MAVEN REPO IS WORKING... INSERT INFO BELOW>

<repositories>
  <repository>
    <id>younite-snapshots</id>
    <name>younite</name>
    <url>https://younite.bintray.com/</url>
  </repository>
</repositories>

4. Once you have these configurations in place for your project, the YOUnite Adaptor SDK will be available.

Dependencies

The YOUnite Adaptor SDK aims to be a very small, easy-to-use library. It is a product of the design goal to avoid external library dependencies 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. The YOUnite Adaptor SDK depends on only one external library: the Google Reflections library. This Using just this one external library minimizes the impact of integrating within existing applications that may use duplicates of the same libraries, possibly of different versions, causing a dependency conflict. The Google Reflections library provides run-time reflection capabilities needed to find and resolve classes and methods.

...

Once an adaptor is connected to the YOUnite DataHub Data Hub through the YOUnite Message Bus, it is able to send and receive data and ops messages. However, to streamline an adaptor developers time, the The SDK has a minimal configuration step so that developers can focus on the business logic their adaptor is being built for and not steps, allowing developers to focus on their adaptor's business logic instead of the inner workings of sending and receiving messages, parsing those messages, and so onetc. To facilitate thisgetting your adaptor up and running, the YOUnite Adaptor SDK makes use of  annotations  developers use of  annotations. Developers use these annotations to define the capabilities related to the data adatpor's capabilities: what their adaptor can produce and/or consume. These capabilities Capabilities loosely translate into a Pub/Sub configuration on the YOUnite DataHub. Essentially they indicate to the YOUnite DataHub Data Hub.

Capabilities tell the YOUnite Data Hub:

• the specific domain properties they

...

• want to receive changes for

...

• which of their

...

• adaptor-associated local services' domain properties

...

• will

...

• be pushed to the YOUnite

...

• Data Hub
• which of their local services' domain properties will be sent when requested by the YOUnite

...

• Data Hub
  
  

Local services could be direct database data, an FTP server, in-memory data, or a remote service with data. In fact, the The dynamic nature of YOUnite domains leave leaves the details to each individual adaptor implementations to implementation. You determine how they access and retrieve your adaptor accesses and retrieves domain property data and what, if any transformations they may want to apply , transformations get applied to the data.

Connecting Adaptors to the YOUnite DataHubData Hub

To get connected to the YOUnite DataHubData Hub, 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.the Active MQ Message Bus transport layer, which requires minimal configuration (described below). The YOUnite Adaptor SDK's flexibilty leaves transport layer options open, however, as the SDK agnostically handles Data Hub connectivity and sending and receiving data. 

Configuring 

Because the YOUnite DataHub Data Hub runtime engine may be deployed in any number of environments (including, but not limited to, local developer machines, QA, Staging, Production, etc..), it is necessary to instruct you must tell the YOUnite Adaptor SDK on how to connect to the YOUnite DataHub. Specifically, Data Hub.

1. Configure the YOUnite Adaptor SDK with the following items:
   • the URL

...

1. • the YOUnite Adaptor SDK will use to connect to the implemented transport layer

...

1. • authentication details

...

1. • that allow the transport layer to identify the specific Adaptor to the YOUnite

...

1. • Data Hub as a legitimate

...

1. • a valid adaptor UUID and Zone UUID (previously registered with the YOUnite

...

1. • Data Hub)

...

1. • possibly the

...

1. • OAuth Server URL used by the transport layer

...

1. • (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)

...

...

1. Create a Config object, provided by the SDK, and

...

1. provide the

...

1. 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

...

Startup

...

1. • configuration changes.

Adaptor Startup

Once the configuration steps above are complete, use the following steps to start your adaptor.

1. Call the AdaptorSDK.init() method

...

1. and pass it either the Config object, or

...

1. the YAML configuration file location. <Add links to example working code here>. 

...

1. The configuration will attach to the transport layer, authenticate, and

...

1. set up data and ops listeners for incoming messages.
2. Behind the scenes, the YOUnite Adaptor SDK attempts to:
   • locate any annotated adaptor classes

...

1. • build the capabilities list from annotated methods within adaptor classes

...

1. • connect to the transport layer

...

1. • send the capabilities list to the YOUnite

...

1. • Data Hub, and
   • build some necessary mappings in memory for the SDK to properly process incoming messages

...

Mappings

Internally, the YOUnite Adaptor SDK maintains data structures to keep track of the capabilities of the adaptor, your adaptor capabilities and the associated domain version(s) of the YOUnite DataHubData Hub. This is what makes it possible to:

• respond to incoming data

...

• send outgoing data

...

• for the purpose of data change detection

...

• (implemented by the adaptor developer

...

• )

Before diving into more details, it is helpful to understand adaptor capabilities and how they are defined.

...

As mentioned previously, when an adaptor is started (by calling the AdaptorSDK.init(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 ) method), it builds the list of capabilities that it must send to the YOUnite Data Hub. The Adaptor Capabilities List consists of the capabilities an adaptor declares to the YOUnite Data Hub upon initialization that 1) link records in the underlying application/service to YOUnite data records, 2) POST entries in the underlying application/service that link to YOUnite data records, and 3) manipulate data in the underlying service.

The capabilities list lets the Data Hub know:

• what data the adaptor accepts (most notably, from other adaptors)

...

• what data the adaptor can provide (most notably to other adaptors)

...

What are these capabilities, and how do you define them?

Capabilities are nothing more than describing:

• a specific domain name

...

• domain version

...

• a set of properties that the domain schema defines (that are associated with the domain name/version)

...

What this means is the Adaptor developer will either:

• work closely with the Data Steward to

...

• define the domains and their

...

• properties (as defined by a JSON

...

• schema representing the domain)

...

-OR-

• use the YOUnite Adaptor SDK's Adaptor Generator tool to quickly build and generate an Adaptor stub (

...

• details below).

The purpose of an adaptor is to be able to :

• get domain/version property data to do something with it (from other adaptors)

...

-OR-

• to send domain/version property data the adaptor is responsible for to other adaptors (via the

...

• Data Hub)

We are defining which properties of a specified domain/version the adaptor is able to work with. The Java  The YOUnite Adaptor SDK provides a set of annotations that are used to annotate for annotating methods within an annotated Adaptor class. The annotations have some properties that are set to annotation properties indicate the domain's name, version, and property properties names within the domain that the annotated method expects as input , or returns as output.

Lets see a simple example, including how we annotate the Adaptor class:

...

@Adaptor(name = "SimpleAdaptor")
public class MyAdaptor {
  @GetFromAdaptor(domains = {
    @Domain(name = "Student", version = "1", properties = {})
  })
  public Student getStudent() {
    return new Student("Jane Doe");
  }
}

Each annotation has a specific purpose. In the above example snippet, you can see a valid Adaptor that utilizes the @Adaptor annotation to specify code example above:

• the @Adaptor annotation specifies the class MyAdaptor is an implementation of an Adaptor

...

• a single method, getStudent(), defines the GetFromAdaptor annotation
• the @GetFromAdaptor is used to define a method that responds to an incoming request to retrieve the specified properties from the local service

...

From the simple example above, you can see a new Student object is returned. More examples will provide details on when and how to use the various method annotations. They all, however, See the list of YOUnite Adaptor SDK supported annotations here: (Insert link to the table of annotations, definitions, etc). 

All annotation have two things in common. First, :

• they always specify at least one domain by name and version. There is no use case for any of the Action annotations being used without a domain name AND version. In fact, the in-memory mapping mentioned earlier requires that the domain name AND version both be provided at all times. If, during the processing of adaptors

...

• , an @Domain annotation is discovered

...

• without a name and version, or

...

• only having

...

• one or the other, a processing exception will occur as the method

...

• will be deemed an invalid annotation use

...

• .
• for every @Domain specified, a properties array is required.

...

• Unlike the requirement to

...

• specify values (such as domain name and version,) the properties array is

...

• a hint to the YOUnite Adaptor SDK

...

• about which domain properties the properties are associated with, this particular method (and ultimately the Adaptor) has the capability to accept or send (depending on the Action annotation being used).

What does this mean exactly? Simply that whenever a @Domain is specified, the object associated with that Domain definition is passed in as a parameter OR returned from the method, again, depending on the Action annotation being used... regardless of the properties specified. So what is the purpose of specifying properties then? Simple. It lets the YOUnite DataHub Data Hub know exactly what properties to send to or expect from an adaptor. For example, in the above snippet, the DataHub Data Hub knows that this adaptor will return a Studen domain object, version 1, back in response to the GetFromAdaptor action... and because no properties are specified, it is essentialy a wild card "*"... meaning any to all of the properties within the domain may be returned as part of the Student object.

...

The above simply tells the YOUnite DataHub Data Hub to only expect the name property of the Student domain (version 1) to be returned. Or more to the point, it tells the YOUnite DataHub Data Hub that the capability of THIS Adaptor is that it returns the Name property of the Student domain, version 1. This allows the YOUnite DataHub Data Hub to use this information to assemble a routing manifest (link to ROUTING details here). So what happens if the adaptor method sets additional properties on the object?

...

It is clear that we have defined only the name property, yet we added age and address to the returned object.  Well one of two things will happen. Either the entire object as it is populated here is sent back (in JSON format) and the DataHub Data Hub simply ignores the other properties based on the fact that the annotation only indicates it handles the Name property... or the YOUnite Adaptor SDK itself may do one of a couple of things... one is to do some extensive checking to ensure that only the properties specified contain data and if anything else is set to anything other than null (which results in the JSON string not containing the property name/value), a runtime exception can be thrown... or 2, modify the structure so that ONLY the properties specified will contain data before the object is sent on its way. Both of these last two options could be possible but as of version 1 of the YOUnite Adaptor SDK the entirety of the object is sent with everything filled and is left for the DataHub Data Hub to deal with.

OK.. so what if we want to work with multiple domains in a single Adaptor class? Perhaps the local service handles students and courses. How would we do this?  Well we could define two @Adaptor classes, each with their own set of annotated methods related to a specific domain:

...

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 Data Hub <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 Data Hub having to do that work (e.g. distribute the load of doing that work to the adaptors to limit the processing needed by DataHub Data Hub 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.

...

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 DataHubData Hub.

Unlike the GetFromAdaptor which can only return a single Domain object, the various incoming data actions can support multiple domain types for one method:

...