Phase 3

Back to the main project page

Introduction

Scope

The first two phases covered data gathering, database consolidation, and web access to a database. Having successfully terminated the data acquisition and integration phase, a web service provider wants to make his data publicly accessible. In the end, the aim of every good web shop is to sell as many items as possible.

Being able to interact with a web shop using programmable interfaces is important in order to reach a maximum of possible clients. We want to use open XML technology to provide a web service that can be invoked using only a minimal programming effort on the client's side. Keeping in mind the troubles experienced in the first phase, this seems to be a very good alternative to parsing HTML pages on the client's side.

The entire phase targets the bidding game that will take place during the last week of the semester. Every team will have a certain amount of virtual money that they can use to bid for CDs on the web shops of all the other teams. This bidding system is based on the use of so-called web services, a concept that has gained more and more significance in the last years.

Aims

This phase will help you understand the basics of a web service and its key components. After this phase you should be able to stress out key points that are in favor or against a web service solution in your own professional future life. Knowing the implementation issues is an important point when trying to achieve this goal.

Warning

This technology might be new to a lot of people. It is crucial to read the provided documentation carefully and to have a look at the examples provided in the official documentation. We strongly encourage you to run the examples you can find in the documentation and try to understand their functionality.

Infrastructure and Concepts

Server infrastructure

In order to complete this phase you will continue to use your current server infrastructure which you should be familiar with by now. The J2EE Application Server will play a central role.

In order to connect to and identify yourself towards other teams, you will be assigned a unique username and password. These credentials will be used to place orders and to determine the winner at the end of the game. It is thus important not to lose or share this information with other teams.

Authentication concept

Buying items over the Internet is a delicate issue. The main reason for this is the lack of a missing trusted party. Whether this is a third party or an integral part of the desired transaction does not matter. The problem is, that you generally do not trust anybody on the Internet.

The idea of our concept is to provide a Trusted Agent and use this entity to secure all desired transactions. The schema should also thwart attacks like forging of bids or refusal to "deliver" items that have been paid for. The Trusted Agent is necessary to avoid sending sensitive information like your private passwords to other teams.

Keeping these requirements in mind, one solution is to use the Trusted Agent as a Ticket Issuing Office. The idea behind this is to send all relevant information to the Ticket Issuing Office where the data is validated and entered into a database. Upon successful registration a Ticket is issued and sent to the client. This ticket guarantees the validity of this transation and can only be used to place the exact registered bid at the Vendor Server.

After receiving the ticket and the related bidding information the Vendor Server has to confirm the incoming bid with the Ticket Issuing Office. (At this point the vendor may also choose to refuse the sale, e.g. because the price offered by the client is lower than the minimal price agreed on.) In order to achieve this, the vendor server connects to the Ticket Issuing Office and confirms that the placed bid has been correctly registered beforehand.

As you might have guessed by now, in practice such a concept can easily be extended to assign the different tasks to separate physical servers for the different entities. We decided to combine the Trusted Agent and the Ticket Issuing Office in order to facilitate the implementation of your Vendor Servers.

Below is a graphical representation of the protocol described above. You will soon discover that it may look more complicated than it actually is. For example, there are only three web service calls involved because every call always consists of two arrows; the request ("method call arguments") and the reply ("return value").

A sample session

To illustrate the aforementioned theory, we would like to provide a simple example: user user01-pc1 would like to buy item item01 from vendor user02-pc2. The listed price is 12.00 but the user is willing to pay 15.30. The intended sequence for this transaction to be fully validated would look like:

1. Ticket issuing request First user01-pc1 sends his ID (user01-pc1), his password (secret-user01-pc1), the vendor ID (user02-pc2), the item ID he received from the vendor's web shop (item01), the list price (12.00), and the price he is willing to pay (15.30) to the Trusted Agent.

2. Ticket issue The Trusted Agent validates the supplied credentials, the existence of the participating parties, the intended transaction, and the proposed price. On success, the agent returns a unique ticket ID (1234567890). In the agent's database, the transaction is now flagged as started but not yet confirmed.

3. Bid placement request Now user user01-pc1 has to place his offer at the Vendor Server of user user02-pc2. In order to do that, he sends his own ID (user01-pc1), the desired item ID (item01), the price he is willing to pay (15.30), and the received ticket (1234567890) to the Vendor Server. (Note that the list price is not included here; obviously the vendor knows the list price of its own items.)

4. Ticket confirmation request The Vendor Server has to validate the received ticket in order to make sure that the user trying to buy an item is authentic. To that end he contacts the Trusted Agent and sends him his client's ID (user01-pc1), his own ID (user02-pc2), the item ID (item01), the list price (12.00), the proposed price (15.30), and the ticket (1234567890).

5. Ticket confirmation response The Trusted Agent in turn validates and checks the incoming confirmation request and returns a result indicating proper registration of the transaction ("commit") or failure to the Vendor Server.

6. Bid placement confirmation The last thing the Vendor Server has to do is to relay the information on the bid registration received from the Trusted Agent to his client. The bidding process is now complete.

After this procedure, the server is certain to have received a valid bid. In real life this would mean that the Vendor Server can be sure to receive his money.

Cryptographic assumptions

Don't let the title scare you off, all of these assumptions are there to simplify the implementation. You will get to know all the tedious details of security and cryptography later in your Master cycle. :-)

The authentication scheme above is not cryptographically secure, it only ensures that under the assumptions described below transactions cannot be faked. So here they are:

• All TCP/IP connections between the machines are protected against attacks like interception, session hijacking, etc. (In practice this would be ensured by using protocols such as TLS combined with trusted certificates.)

• The ticket numbers generated by the ticket issuing office cannot be guessed. (In practice the use of large numbers consisting of 128 or more bits provides good enough security against brute-force attacks.)

The Tech Part

Documentation

In principle, this section could be the shortest of the whole phase description. The most important resource has already been created and is called The J2EE 1.4 Tutorial. Don't be afraid, you are not required to read the whole tutorial to finish this phase. The most important information is located in chapter 8: «Building Web Services with JAX-RPC». Take your time and read the information provided in this chapter carefully. A lot of problems can be solved by looking only at the information provided in this tutorial.

You can download the J2EE tutorial containing all the sample files directly from our web site:

j2ee-1_4-doc-tutorial_4.zip (16.8 MB)

Interfaces

In essence, a web service is nothing else than a piece of software that can be invoked through a network. Instead of calling local methods, a remote object's methods are invoked by the caller. To be able to determine the kind of method signatures, Interfaces are provided to the caller. It is now the programmer's task to use these interfaces to create valid calls to the server methods.

The following sections should give you an idea of the methods provided by the Trusted Agent. Furthermore, we give you an interface (BiddingIF.java) that has to be implemented by your Vendor Server. It is important to remember that these interfaces must not be changed. Non-conformance to these interfaces would result in the inability to call your server's methods from a bidding client.

The Trusted Agent Interface

The Trusted Agent provides only two public methods. These methods are used to create a new ticket (step 1 in the example above) or register an issued ticket (step 4).

int requestTicket(int buyer, String password, int vendor, String item, float bid, float price);

int confirmBid(int buyer, int vendor, String item, float bid, float price, int ticket);

Complete Trusted Agent Interface (AgentIF.java)

Have a look at the authentication scheme again to fully understand why both methods are required. The Trusted Agent has the ability to return different type of responses. All possible error codes are coded as a bit field and returned as a plain integer to the calling instance. Your programs can thus check why a request failed if you did not receive a valid ticket number. As you can see in the interface definition, all valid tickets are greater than TICKET_MIN.

The Vendor Server Interface

Your Vendor Server also provides methods to communicate with the outside world. It has to be able to accept and respond to bids placed by your clients and does this with the help of a single method:

boolean placeBid(int buyer, String item, float bid, int ticket);

Please read the comments in the interface definition to get more information.

Complete Vendor Server Interface (BiddingIF.java)

Transmitting bidding information

This part is optional in the sense that it is not required to have a sufficient (or even a higher) grade. However, its implementation is both very easy to accomplish and recommended since it is a big help for customers of your webshop, something that will pay out in the bidding game, simply because it makes the shopping process easier for them.

As you can see from the ticket requesting interface above, it can be a little tedious for customers of a web shop to transmit three different data (vendor number, item ID, and list price) to their bidding client. In order to simplify this task we have defined a format that combines these three data in a single string. A web shop supporting this format would display this string next to each item. The shopping person can then just copy it and paste it into their bidding client, which can then reextract the data for reuse in the ticket requesting process.

delimiter        = '/'
fielddelimiter   = '_'                            // only when neither preceded nor followed by another fielddelimiter

Vendor           = DECIMAL_LITERAL                // a Java integer
Item             = STRING_LITERAL                 // a Java string
Price            = FLOATING_POINT_LITERAL         // a Java float

BidInfo          = delimiter Vendor fielddelimiter Item fielddelimiter Price delimiter

There is no need, however, to write any parsing functions for this format because we provide you with a simple class that does exactly this:

BidInfo.java and its JavaDoc description

The class is easily integratable in your web shop and bidding client. You can see some examples of how it works by looking at the test cases in its main function.

Testing

Obviously, creating such an application requires quite some testing until it reaches a fully functional state. In order to facilitate testing we set up a Vendor Server that can be used by your client to place bids during the development and testing phase. Our testing server provides exactly the interface you are also required to implement in your server. Since we don't have any CDs to be sold, you should use the same value for the bid and list prices. This is required since the Vendor Server has to confirm the placed bid at the Trusted Agent which includes sending the list price. Moreover, the identification used by the Test Vendor Server is 0. When you register a ticket, you will have to transmit 0 in the vendor field.

During the first development phase you might be interested in checking your Vendor Server's own functionality. Therefore, the Trusted Agent allows placing bids on your own server until the bidding game starts.

Using System.err

As you might recognize soon, webservices are somewhat different to debug than normal Java programs that are called by a user on an ad-hoc basis. You cannot just output values to the console the same way you would do in an ordinary program using System.out.println(..). However, and easy way of printing values directly when the program arrives at a certain point is by using System.err.println(..). This procedure does not print to STDOUT but to STDERR. For a web service, STDERR is redirected to the server log file which resides in /opt/j2eeXX/domains/domain1/logs/server.log. Use the UNIX command tail to display the last lines of the error log.

Text Logging Facility

Another commong method of controling the execution flow of a program could be to use a text logging facility that writes to a normal text file. This has got the advantage that you can easily separate your messages from the log entries generated by J2EE in the standard server log.

/*************************************************************************
  * Text logging facility
  ************************************************************************/
private static final String LOG_FILE = "mylog.log";
private static PrintWriter log = null;

private static boolean openLog()
{
    try {
        log = new PrintWriter(new FileOutputStream(LOG_FILE, true));
        return true;
    } catch(FileNotFoundException e) {
        System.err.println("ERROR: Could not create log file.");
        e.printStackTrace();
    }

    return false;
}

private static void writeLog(String entry)
{
    if(log == null && openLog() == false) {
        System.err.println("ERROR: Cannot write log entry: file is not open");
        return;
    }

    log.print(new java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new java.util.Date()));
    log.println(" " + entry);
    log.flush();
}

When using this code, you might find the created file in the config directory of your domain: /opt/j2eeXX/domains/domain1/config/mylog.log

Bidding log

We provide you with a web site where you can list the bids that you have successfully placed. You can use the credentials that you have received by e-mail to log in.

Bidding log

Note that the database will be flushed when the bidding game starts, so feel free to place as many fake bids as you need to test your web services.

Requirements

Your task is to create two web services: a Vendor Server and a Bidding Client. The server will be used to accept incoming bids and confirm them with the Trusted Agent. The client is necessary to request tickets from the Trusted Agent and to place bids at the Vendor Server. Note that the client does not have to be fancy, it just has to be functional. This means that a very simple command line interface will do and you are not required to build a nice GUI, although we will certainly not stop you from doing so. :-)

Think about the concept before you start. Make sure you understand the details of the authentication protocol before you even launch your favorite text editor to write the Java code. The pieces in this phase will not work if you don't understand what is going on under the surface. We can only stress the importance of the mentioned tutorial again.

Report

Please read the following list of required parts for the final hand-in carefully and make sure your archive is complete.

• All files required to deploy your Vendor Server (.java, .xml, .wsdl and a copy of your .war)
• All files required to build your Bidding Client (.java, .xml)
• The complete project report (in valid XHTML, as usual)

Grading scheme: In order to receive a good mark in this phase, your web service has to be able to accept and react to valid bids. This includes accepting the incoming bid, confirming it with the Trusted Agent and returning the result to the client. Your web service has to sanity check incoming bids as it would be done in a real-world application. Furthermore, your service has to be immune to similar attacks as already performed in phase 2.
In addition, your bidding client has to be able to request a ticket at the vendor server and place the bid at any of the other team's Vendor Servers. In order to receive a good mark, you are not required to program any top-notch graphical user interface. A basic but functional text interface does the job!
A potential client has to be able to clearly get the item identifier from your web shop to be able to purchase an item.
Finally, you have to supply a short documentation covering how to build and deploy your Vendor Server and Bidding Client.

Some words concerning the report: Like for the previous phases the report should contain problems you've encountered, how you've solved them, the techniques you have used for the different tasks. The report represents your work for this phase of the project, so be sure to include everything that you think is important. However, since this phase does not involve a lot of theoretical work, the expectations in terms of report length are lower than in the previous phases. You are not required to document your code again in your report if you have a good level of code documentation in your sources.

Some groups handed in their merging scripts and SQL schemas in barely readable image form (like JPEG – ever heard of compression artifacts?). Obviously this is not an acceptable format, for one part because we may want to try out parts of your scripts and for the other because that is simply not what images are for. So for phase 3 large amounts of text in image format will lead to (more) serious deductions. (This paragraph really shouldn't have to be here ...)

Finally, note that you must not send any database dumps this time and that you have to send everything to Patrik! If you don't follow this, your report may not arrive in time for grading!

Deadline for report hand-in: Friday, 2005-06-10, 2400 (hand-in by e-mail to Patrik)

Outlook

The final step of this project is a bidding game. More details are available on the Bidding game page. Every team will participate in this game and try to buy and sell as many items as possible. The Trusted Agent will perform the final evaluation and determine the winners of the game.

Note that there is no report required for the bidding game.

Copyright © Martin Rubli & Patrik Bless – Last change:
This page uses valid XHTML 1.0 Strict and valid Cascading Style Sheets, Level 2. This page uses valid XHTML 1.0 Strict. This page uses valid Cascading Style Sheets, Level 2.