Protocols for working together - nordquip/sousms GitHub Wiki

##GitHub Team Forks Each team will create a fork from SOUSMS.
Then each individual on the team will pull their team’s fork to their local system.

When team forks have a consistent and working set of code, then the team’s designated repository person will pull down any changes from the master repository and check for errors. If this update succeeds, the repository person will then integrate the team fork into nordquip/sousms. Ryan has produced instructions on how to do perform these operations: Group Fork Merge Process

##Git markdown format for documentation Please use markdown format (file extension .md) for documentation files in the repository. This is the format you use when you edit wiki pages on github.com. It looks a little funny, but is easy to read and write in raw form and makes a nice web page on github.com.

Interfaces

In a project where many people are involved, eliminating bottlenecks and preserving independence are treasured goals.

We want to create protected ‘sandboxes’ where people can work without interfering with others. The primary tool for accomplishing this goal is through well-defined interfaces. (APIs are such interfaces.) Interfaces provide a way for a service provider to:

  • Localize changes to a single place
  • Limit the things one group must know about another

An interface is the place where two separate portions of the system meet. We have a three tiered system:

  1. UI layer -- gives and receives data directly from the user
  2. Middleware -- accomplishes tasks on the user's behalf
  3. Database -- holds the data

Our project has two kinds of interfaces:

  1. Web services -- these implement portions of the system that perform some task the user wants to accomplish (the middleware). Web services are called by portions of the system that communicate directly with users (the UI layer).
  2. Stored Procedures -- these provide a way for Web services to communicate with the database to enter and retrieve data they need to accomplish their task.

Web Services

Jeff Miller has written us a very nice demo, which implements a web service that implements the login interface.

Service providers

Service provider sample coded is contained in two files:

  • ua.php (takes all requests for webservices provided by user accounts), and
  • Credentials.class.php (provides data and functions needed by the login behavior).
    A behavior is a task that the UI layer calls. Each behavior provided by user accounts will have a different .class.php file. Each user account behavior will have a different 'case' in ua.php.

The trade engine will also be a web service provider that provides a set of behaviors needed by the UI layer to accomplish trading actions for the user.

Stored Procedures

Stored proecedures ‘wall off’ the database, by enforcing a protocol that SQL commands are not issued from anywhere but a stored procedure.

Stored procedures are the 'slick' between the middleware and the database.

Web services call stored procedures. Stored procedure headers (what would be the method signature in java) are the responsibility of the web service thatr calls them.

Stored procedure bodies (the part between the 'begin' and 'end' statements are the responsibility of the database group.

Example

The user wants to say something like:

‘Buy 100 shares of INTC’, so we create a behavior in the Trade engine:

buy(usertoken, symbol, numberShares)

This procedure must:
* Identify the current user
* Check to see if this user has enough cash to buy numberShares at price.
* If so, decrement the user’s cash account appropriately, 
add numberShares of symbol to the user’s stock account,
and return 'successful'
* If something goes wrong with any of the above, return an appropriate error message.

Notice, the 'return value' can be specified as part of the description of the interface.
Return values can be arbitrarily complex, including a list of items.

The buy behavior of the Trade Engine web service:

Implements the actions shown above in the description of the behavior. In doing so, it must call at the following stored procedures:

  • getUserIDFor(token)
  • getCurrentPriceForSymbol(symbol)
  • enoughCashFor(userID, priceReturnedByGetCurrentPriceForSymbol())
  • buy(userID, symbol, #shares)

All interfaces must be reviewed and documented, which isn't yet finished.

See the Interfaces section of <cs.sou.edu/~nordquip/cs469/notes/week04notes03.htm> for an example of how to create and use a stored procedure interface as an interface.

Development Environment

Set up your development environment with an *AMP stack.

Building sousms on your development platform

See http://cs.sou.edu/~nordquip/cs469/notes/week04notes03.htm for a general description of what the build does.
See https://github.com/nordquip/sousms/blob/master/src/README.md for how to build sousms on your development platform.