Repository navigation
Home
Getting Started
The term "cloud" is used to referred to the deployed instance of the wayf-cloud Java application. It provides a RESTful Java API for third parties to interact with. Portions of the API are restricted to registered publishers or authenticated administrators. However, any user of the WAYF cloud may access the data collected for their device at any time.
In order to facilitate publisher integrations, a small Javascript file is provided to each publisher upon their approved registration. This file contains publisher specific applications keys that allows them to register devices with the WAYF cloud by associating a device with a publisher specific "local ID". The template for this file may be found in src/main/resources/wayf_widget_template.js.
The "widget" is intended to only support registering a device against a local ID. For full integration of all available publisher actions, technology specific clients are provided. For example Java and Node
The user interface portion of the application is found in the Admin App. Here publishers may request to be a member of the platform, users may view their data, and administrators can perform tasks vital to the WAYF system.
The following is intended to serve as a high level overview of the various technologies employed by the WAYF cloud. It is expected that developers have an understanding of the functionality provided by each library as well as how to use it.
Guide
Git was chosen as the source control system for WAYF cloud. New functionality should be developed in feature branches. These can then be evaluated in a pull request before merging to a shared branch.
Guide
Maven is responsible for maintaining the list of dependencies required to build the project. Additionally, instructions on how to package the fat, deployable jar are defined in the Maven pom file.
Guide
A rather straightforward implementation of MySQL serves as the database.
Guide
Redis is utilized as a caching layer. A DAO containing the connection information is provided in com.atypon.wayf.dao.impl.RedisDaoImpl.
Guide
The WAYF cloud makes heavy use of Java 8 lambas. It is strongly recommended that a developer familiarizes themselves with lambdas before working on the cloud.
Guide
Vert.x is a node-eque event loop that provides the HTTP server. More information about the Vert.x implementation is contained in the REST API wiki page.
Guide
Reactive streams allows for event based development with a strong focus on multi-threading. It is important to understand the Reactive API and it's features before working on the cloud.
Travis CI is a build tool that allows for projects to be built in a freshly installed environment each time. Dependencies, such as Redis and MySQL, are installed from scratch on each build. This provides both a built-in data cleanup as well as isolation from from other builds or user actions. For open source projects, Travis is free.
As mentioned above, each Travis build is run against a newly installed MySQL database. Because of this, the database schema, tables, and user must be bootstrapped into the new instance on each test run. The two files that specifically address this are src/test/resources/create_wayf_db.sql and src/test/resources/create_wayf_tables.sql.
In addition to table structures, a default administrative user, password, and API token are created in the migration. The test cases rely upon this default user. For deployed instances, this user allows an admin to log into a new environment for the first time and create additional administrators. The default user should be deleted from deployed instances of the code once additional administrators are created.
The reliability of the WAYF cloud is ensured via automated test coverage. Core system utilities have unit tests. However, the vast majority of business logic is covered with integration tests. These integration tests extends com.atypon.wayf.verticle.routing.BaseHttpTest. This base class is configured with test utilities that wrap specific HTTP calls. For example, requests to create a publisher would be found in com.atypon.wayf.integration.PublisherTestUtil. Each test util will take input, serialize it, execute a HTTP request against an embedded WAYF server and make assertions on the output. The output is compared to static JSON files located in the codebase. com.atypon.wayf.integration.HttpTestUtil contains some useful methods in comparing and manipulating JSON. It will also allow for JSON comparisons that will ignore and server generated fields -- such as IDs and createdDates -- in the form of a field blacklist.
The integration tests are very strict on the response from the server. For example, the following are NOT considered equivalent:
{ "id": null } vs {"id": {} }
{ "ids" : [] } vs { "ids" : {} }
{ "id": null } vs { "id": null, "modifiedDate" : null }
The point of such strict output is to ensure consistent responses to third-party clients.
In addition to the test utilities, the com.atypon.wayf.verticle.routing.BaseHttpTest will also log all of the HTTP request/response for a test class. The location of this file is the constructor argument to each instance of BaseHttpTest. This can be a useful file in helping a developer understand the client/server interactions. It does not drive any test logic.
The build process runs the entire test suite. The test suite relies upon the default token for the administrative user remaining the value that was set in the database bootstrap. Logging in as this user will reset the token and cause test case failures.
Test coverage is tracked by codecov.io. This is free for opensource projects. This is mainly useful for understanding the test coverage impact of pull requests.