.. index:: single: Use Case Diagram
The application used for this tutorial is a web-based book recommendation system that provides a list of books available on Project Gutenberg and provides recommendations of other books. You can run the application at http://www.impactsoftwarelabs.com/book and view the full source code here
A use case diagram showing the major functions is listed below.
.. index:: single: Current State Diagram
A diagram of the current state implementation is shown below.
The primary components are:
- PHP is used to dynamically generate Web pages that are served by an Apache Web Server.
- A MySQL database is used to store the book catalog, user ratings, and recommendations.
- An open-source recommendation engine named MyMediaLite is used to process each user's book ratings and generate recommendations.
- Small Java programs are used to interact with the recommendation engine, and to download and process the book catalog.
The book catalog contains approximately 50,000 books and the number of users is relatively small.
.. index:: single: Future State Diagram
The existing system will be re-engineered to use a broker pattern where the various components are decoupled and potentially distributed. A diagram of the future-state implementation is shown below.
The primary changes are:
- Creation of a Book Service that will interact with the web pages using a RESTful API. This service will be managed and executed using CloudI and will be created using the Erlang programming language.
- Use of a CloudI MySQL Service Adapter to provide location transparency for the MySQL database backend.
- HTML pages will call the Book Service directly using Websockets rather than being generated by PHP on the server side.
- Modify the various Java utility programs to run as CloudI services and use the MySQL Service Adapter rather than calling the MySQL database directly.
Note
The Future State Implementation could be further simplified by using the Cowboy Web Server rather than the Apache Web Server for serving the HTML pages. However, in the target environment there are other applications using Apache and Apache is the corporate standard.
.. index:: single: JSON
Because the components will be developed using different languages (Javascript, Java, and Erlang), an important decision is to select a language-independent method for transmitting data between each component. CloudI does not impose a specific data transfer mechanism, so you are free to select this. In this tutorial, the JSON protocol will be used with the following libraries:
- Java - TBD
- Erlang - jsx. Note that jsx is built into the Cloudi distribution and is located in the module named cloudi_x_jsx.
.. index:: single: RESTful API
Another important point is to design a consistent RESTful API for interacting with your services. CloudI uses the Cowboy HTTP Server to handle requests and Cowboy supports the standard range of REST methods including: GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS. Additional information about Cowboy is available here . An excellent resource for designing RESTful API's is located here
The table below lists the different use cases, HTTP methods, and URL examples implemented by the Book Service. Note that the top-level URL will be /book
| Use Case | Method | URL | Description |
|---|---|---|---|
| Browse New Books | GET | /book/newbooks | Return list of new books |
| Browse Popular Books | GET | /book/popularbooks | Return list of most-popular books |
| Browse Recommended Books | GET | /book/recommendedbooks?user=X | Return list of recommended books for the given User ID |
| View Book Details | GET | /book/allbooks?id=X | Return details about book given the Item ID |
| Download Book | GET | /book/download?id=X&user=Y | Download a book given the Item ID and User ID |
| Create New User | GET | /book/newuser | Create and return a new user ID |
| Get Unrated Books | GET | /book/unrated?user=X | Get the unrated books for a user ID |
| Rank Downloaded Book | POST | /book/download/ | Update a book's rating given the User ID, Item ID, Rating |
| Add Book to Collection | POST | /book/allbooks/ | Add a book to the collection |
Note
As described later in this tutorial, access control lists are developed using URL patterns. Consequently, give some thought to developing a consistent URL structure.
There are several different methods for applications to call CloudI services. The alternatives depend on whether the application is "external" (i.e., run inside an operating system process external to the Erlang VM) or "internal" (i.e., run inside the Erlang VM). Applications written in C, C++, Java, JavaScript, Perl, PHP, Python, and Ruby would be of "external" type. Applications written in Erlang or Elixir would be an "internal" type.
| Application Type | Integration Method | Comments |
|---|---|---|
| External | HTTP | Using WebSocket protocol |
| External | Zero MQ | Use Zero MQ as a messaging bus. See Cloudi FAQ for details |
| Internal | CloudI API | Setup Subscribe/Request pairs. Messages can be synchronous, asynchrous, or broadcast |
Additional information is available in the CloudI FAQ here .
Note
Technically an Internal application could also use the HTTP or ZeroMQ integration methods, but generally the use of the CloudI API is preferred.
For this application, HTTP REST calls will be used to integrate the HTML pages with the Book Service. The HTTP request/response messages will be delivered using the WebSocket protocol. The Java Utility programs will use the ZeroMQ message bus.
.. index:: single: Data Model Diagram
A diagram showing the database tables and their interrelationships is shown below.
The primary tables are the items and users table. Several cross reference tables exist including:
- user_items - tracks which items a user has downloaded and if they have submitted a rating
- user_item_recommendations - contains recommendations for a particular user
- user_item_ratings - holds the rating value that a user submits for an item