Project 1d: Web Services

This is the final step of the Project. In this step, as promised, you will convert the Event Provider and Bank logic to be accessed as Web Services.

Due: 7 May 2005.

The Web Services

Each service (Provider and Bank) will be implemented as a Stateless Session Bean exported as a Web Service using JAX-RPC. A discussion of this appears in the O'Reilly EJB book. I have put a copy of the Workbook deployment descriptors and WSDL files here; the entire Workbook is available here.

The Bank

Recall the Bank Web Service needs methods to

• check the balance of an account (to check the customer's credit).
• deposit or withdraw a specified amount from an account.

We'll model these with the following signatures. First, for checking credit:

public int checkBalance(int cid,
     int acctid, float amt)

where

• cid is the unique id of your casino site.
• acctid is the customer's unique account id.
• amt is the amount to be verified.

and the result encoding is

• 0 = okay.
• 1 = the account can't cover this amount.
• -1 = the casino (cid) doesn't exist.
• -2 = the account (acct) doesn't exist.

Note we really ought to be using exceptions rather than negative return codes, right?

Now, for paying or billing:

public int updateBalance(int cid,
     int acctid, int invoiceid, float amt)

where

• cid is the unique id of your casino site.
• acctid is the customer's unique account id.
• invoiceid is a unique id for this business transaction (discussed below).
• amount is the amount to be added to the account.

and the result encoding is

• 0 = okay.
• 1 = the account can't cover the amount (this can happen only if amt is negative).
• 2 = this is a replay of a previously seen invoideid.
• -1 = the casino (cid) doesn't exist.
• -2 = the account (acct) doesn't exist.

Again, we really ought to be using exceptions rather than negative return codes.

The use of the invoiceid was discussed in lecture: if the Bank is transactional but does not support distributed transactions using Web Services (this is still a common situation) your site can assign a unique invoiceid to each wager, and achieve exactly-once semantics for billing actions by relying on the Bank to record (transactionally) whether a given invoiceid has been processed yet.

Provider

Recall a Provider has methods to

• return information about the next event (known to the provider) whose “opening” or “announcement” time is after a specified time.
• return the information about an event given its event id.

Ideally these should be implemented as methods that return a structured type containing all information about an event. But you may find it more convenient to implement the functionality as multiple “getter” methods, each returning a simple type. Since the events themselves are accessed infrequently the extra network traffic resulting from this should not be egregious. (Note your casino should contact a provider site only once to learn about an event, and only once to determine the outcome). Either approach is acceptable.

If you take the“getter” approach, the method signature to learn about an event is

public int getNextEvent(java.util.Calendar after)

The return value is the unique event id of the next event whose announcement time is greater than after. (If there is no such event, the return value is 0). The “getter 8; methods have simple signatures:

public Calendar getAnnouncedTime(int evtid)
public Calendar getScheduledTime(int evtid)
public String getDescription(int evtid)
public int getOutcome(int evtid)

where the result encoding for getOutcome is

• 0 = the event has not yet happened.
• 1 = outcome is 1 (for a contest, “the first participant wins”).
• 2 = outcome is 2 (for a contest, “the second participant wins”).

Note there is no cid parameter in any of the above signatures. A provider is willing to tell anybody about its events, and does not keep track of who has asked.

Note: Because it is invonvenient to implement more than one provider instance on your local machine, I will not ask you to do this – a single provider will suffice.

The Implementation

You will need WSDL files, Endpoint and Service interfaces, stateless Bean classes implementing the service methods described above, and of course the appropriate deployment descriptors. Of course, the method implementations should be straightforward adaptations of the JDBC code you implemented for Part 1c. But getting working WSDL and descriptor files is not trivial. A reasonable approach is to examing the WSDL and descriptor files from the Workbook examples and make the necessary modifications. Another thing you might consider is the Java2WSDL tool, which automatically generates a WSDL document from a plain Java interface for the Service Endpoint.

Note that JBoss doesn't actually require a JAX-RPC precompilation step to generate stubs – it's logically there, but in JBoss it's done dynamically (and automatically) at deployment.

This is the hard part! Eventually you should get your site working again as before, but now with a Bank service and a (single) Event Provider service implemented as stateless session EJBs and accessed through Web Services interfaces.

Project Description File

Create a short design document summary.pdf for your project implementation. It should include:

• a list of the EJBs (entities and session beans) and description of their relationships (figures are useful)
• a brief discussion of fault tolerance: how does your design deal with transient failures in the netowrk, Bank or Provider sites?
• suggested improvements

What to Submit

Create a .zip archive called proj1d.zip containing the following:

• your summary.pdf file
• the source files of your Java code and deployment descriptors
• screen shot of your website showing a customer's page with multiple events available for wagering and multiple outstanding wagers, both before and after one of the events (that the customer has wagered on) has occurred.

Submit the zip file to CMS by the due date. Note the absolutely hard due date for this part is the Official Scheduled Final Exam Time for this course: May 18.