DESIGN DOCUMENT FOR VIPANI

DESIGN DOCUMENT FOR VIPANI-A VIRTUAL AUCTION HOUSE

1. INTRODUCTION

This report documents the software modeling, analysis, architecture, and design of VIPANI, an electronic auction house where registered users can sell and buy item(s) either by setting up auctions or participating in auctions. UML (Unified Modeling Language) has been used in VIPANI modeling. The key features of VIPANI architecture and design are extensibility, reusability, robustness, and scalability. These features have been achieved through the use of best practices in software engineering such as design patterns.

This report is organized as follows. Section 2 presents the requirements definition for VIPANI where we crystallize three top level requirements. Section 3 is devoted to object oriented analysis of VIPANI. In this section, the software requirements specification is presented first, followed by a detailed use-case model, accompanied by a description of the use cases. This is followed by a domain analysis where an analysis level class diagram is presented. Sequence and collaboration diagrams are presented next. In Section 4, the discussion is centered on VIPANI architecture. A solution model, a technology realization model, a J2EE realization model are described. Section 5 presents the design model in the form of a design level class diagram. The emphasis in this section is on the use of the following design patterns: Abstract Factory, Strategy, Factory Method, Iterator, Observer, MVC, Singleton, and Proxy. In Section 6, component model is presented.

2. REQUIREMENTS DEFINITION

In this section, we present a crisp requirements definition for VIPANI, starting with a goal.

Goal: The goal of VIPANI is to automate the process of buying and selling. VIPANI is a virtual auction house where users can sell/buy item(s) using different business models like auctions, exchanges etc. The users actually do trading by creating agents who work on users behalf.

2.1 Top Level Requirements Definition

RD 1 Develop a software system that allows users to sell/buy good(s) through different business models.

RD 2 The system should allow the creation of new (1) auction mechanisms and formats. In short, it should be an extensible system.

RD 3 The system should provide a messaging infrastructure that supports the exchange of messages between the system and a variety of messaging clients (web browsers, email clients, PDA’s and mobile phones in a device independent manner)

The above three top level requirements form the basis for the next phase of the process, namely requirements analysis and domain analysis.

3. ANALYSIS OF VIPANI

Analysis is a process of identifying the conceptual items and properties necessary for a solution to be both correct and proper. Our approach partitions the analysis process into two phases: Requirements Analysis and Domain Analysis. During the requirements analysis, we reformulate and expand an informal set of requirements into a more formal description. This transformation is done gradually through use cases. Use cases offer a systematic and intuitive way to capture the functional requirements with particular focus on the value added to each individual user or to each external system. Use cases play a key role in driving the rest of the development work and that is the important reason for their acceptance in most approaches to modern software engineering. In Domain analysis, based on the set of use cases, domain classes are recognized and their relationships are captured .

3.1 Software Requirements Specification

We expect VIPANI to have the following stakeholders:

1. Buyer(s)

2. Buying Software Agent(s)

3. Supplier(s)

4. Supplier Software Agent(s)

5. System Administrator

The stakeholders’ requirements are captured below:

SR 3.1.1 Buyer

SR3.1.1.1 Buyers must be able to login, change passwords, and browse ‘relevant’ parts of the system.

SR3.1.1.2 They should be able to check the status of ongoing auctions created by them.

SR3.1.1.3 They should be able to create new auctions, and modify the rules of a predefined auction before it has started.

SR3.1.1.4 They should be able to close the auction.

SR3.1.1.5 They should be able to define new auction formats.

SR3.1.1.6 They should be able to browse a user catalogue and select users who could be invited to participate in an auction.

SR3.1.1.7 They should be able to browse a auction catalogue and select the auction in which he should participate.

SR 3.1.2 Buying Agent

SR 3.1.2.1 The buying agent is a software agent created by the agent to participate on his behalf in an auction.

SR 3.1.2.2 He will be submitting the bids on behalf of the user. He can make the payment through secure means on behalf of the

user.

SR 3.1.3 Seller

SR 3.1.3.1 Sellers must be able to login, change passwords, and browse ‘relevant’

parts of the system.

SR 3.1.3.2 They should be able to check the status of ongoing auctions created by

them.

SR 3.1.3.3 They should be able to create new auctions, and modify the rules of a

predefined auction before it has started

SR 3.1.3.4 They should be able to close the auction

SR 3.1.3.5 They should be able to define new auction formats.

SR 3.1.3.6 They should be able to browse a user catalogue and select users who could

be invited to participate in an auction

SR 3.1.3.7 They should be able to browse a auction catalogue and select the auction

in which he should participate

SR 3.1.4 Seller Agent

SR 3.1.4.1 A selling agent is a software agent created by the user to participate in an auction.

SR 3.1.4.2 He will submit bids on his behalf and capable of making payment too on his behalf.

SR 3.1.5 System Administrator

SR 3.1.5.1 The SysAd sets up profiles for buyers and sellers (market participants).

SR 3.1.5.2 He should be able to add new products to the existing Catalogue.

SR 3.1.5.3 He should be able to remove products from the Catalogue.

SR 3.1.6 System

SR 3.1.6.1 Whenever the SysAd creates the profiles of buyers or sellers, the System should notify the corresponding user about his account information.

SR 3.1.6.2 During the auction set up by the buyer, the system should send notifications to the mentioned set of suppliers if it is not an open cry auction.

SR 3.1.6.3 Whenever the auction close time is reached, system should determine the winners, price to be paid by the buyer for the winning sellers and notify the corresponding buyer and suppliers (subject to the buyer’s approvals).

SR 3.1.6.4 The system notifies the users of any relevant information about the auction.

3.2 Use Case Model

A use case model describes what the system does for each type of user and provides the essential input for analysis, design, and testing. It is a top-level view of the system and shows the actors, use cases, and their relationships. The actors are entities that interact with the system. From an understanding of the stakeholders of the system, we have identified the following actors: System Administrator, Buyer, Buying Agent, Seller, and Selling Agent.

Use Case Diagram

A use case diagram for "setup auction" use case

A use case diagram for "participate in auction" use case

3.2.1 Use Case Descriptions

1. Login Use case

a. Assumptions

i. The user is already registered in the system as a Buyer /Seller/System Administrator.( User Registration may be an off-line process)

b. Main Flow

i. The User enters his User name and password.

ii. The System determines whether the particular user is registered. (E1)

iii. If the user is registered, the system determines his category (e.g., Buyer, Seller, System administrator).

iv. The system displays the corresponding interface for the particular user category.

v. For each user the system allows him/her to change his profile as part of his interface in all the pages that follow. (E2)

c. Alternate flow

i. E1: User name/ Password are incorrect. The System takes the User back to the Login page and prompts for a re-login.

ii. E2: Inputs are invalid.

iii. The System provides the parameter input interface again for correcting his inputs.

2. Logout Use Case

a. Main Flow

i. The User Exits

ii. The system persists the user activity history.

3. Setup New Auction Use case

a. Main Flow

i. The user chooses to setup a new auction.

ii. He chooses the product(s) to be auctioned from the catalog of products.

iii. He sets the rules for the auction.

iv. He sets the Starting/Closing Date/Time of the auction.

v. He chooses the algorithms for determining winners and price.

vi. He approves the list of users to invite, and the list of user-specific items that each user will be allowed to bid on.

vii. The System sends notifcation to the list of users already supplied by the user in case it is not an Open Cry Auction.

4. Check Auction Status Use case

a. Main Flow

i. The user browses the catalog of auctions set up by him.

ii. The user chooses the necessary auction whose status he wishes to check.

iii. The system displays the auction status.

5. Modify Auction Rules Use case

a. Main Flow

i. The buyer chooses an auction from the list of auctions interface.

ii. The buyer opts to modify its rules.

iii. The system verifies his authority to do so. (E7)

iv. The buyer changes the rules of the auction.

b. Alternate Flow

i. E7: The auction has already started.

ii. The system informs the buyer that the rules can’t be modified now.

6. Close Auction Use case

a. Main Flow

i. The buyer chooses to close an auction.

ii. The system determines the winner of the auction and informs both the buyer and the winner/s (subject to buyer approval) about the details.

iii. The system closes the auction and updates the list of auctions.

7. Check Bid Status Use case

a. Main Flow

i. The user chooses to check his bid status.

ii. The system displays his bid and the current round number of the auction and the winning price for the previous round.

8. Auto Close Auction Use case

a. Assumptions

i. The closing date/time of an auction is reached.

b. Main Flow

i. The system determines the winners by choosing the algorithm specified by the user during the setup of auction.

ii. The winners are informed about the auction. (E8)

iii. The owner is informed about the winners and the other relevant details.

iv. The auction status is updated.

c. Alternate Flow

i. E8: There are no winner/bidders

ii. The owner is informed and the auction status is updated.

9. Determine winners Use case

a. Assumptions

i. The auction has a valid set of bids.

b. Main flow

i. The system collects all the bids

ii. The system uses the winner determination algorithm as set by the buyer and computes the winning bids (E9)

iii. The system closes the auction and notifies the winners.

c. Alternate flow

i. E9: The auction in multiple round auction

ii. The system notifies the bidders on the current round details.

10. Notify User Use case

a. Main Flow

i. The system sends the message to the users (buyer/sellers).

3.3 Domain Analysis

The information gathered during the construction of the use-cases was used to perform the object decomposition and build the object structure of the system.

Object identification: The key objects identified were: AuctionHouse, Auction, Bid, Buyer, Seller, Item, Buying Agent, Selling Agent, System Admin, User Catalogue, Auction Catalogue,Agent Catalogue, Item Catalogue, Rules
Identification of relationships: The relationships between major classes were classified as follows:

FABid, RABid etc are a type of Bids.
FEABid, FDABid, FFPABid, FSPABid are types of FABids.
Buyer, Seller and System Admin are a type of users.
Buying Agent, Selling Agent are types of Agents.
Bid is a part of Agent. So they strictly fall into Composition relationship.

We present the analysis level class diagram based on the classes and their relationships as identified above. We also present the interaction diagrams to show how the objects communicate.

3.3.1 Analysis Level Class Diagram

The UML profile specifies a number of stereotypes for packages, classes, and relationships. It describes three particular stereotypes that are applied to classes. They are:

Boundary Class: The stereotype <<boundary>> is used to describe a class that acts as an interface to the system -- it interfaces classes outside the system with classes inside it. Here WebInterface are the boundary classes.

Control Class: The stereotype <<control>> is used to describe a class that exercises control over other classes, or acts upon them. Here classes such as Buyer, Seller, System Admin, AuctionExecutor, AuctionHouse, Auction, Notifier, Authentication Unit are the control classes.

Entity Class: The stereotype <<entity>> is used to describe a class that carries data, is acted upon by other classes, and is generally persistent. Here classes such as AgentDB, AuctionDB, Agent Catalogue, User Catalogue, Item Catalogue, Bid, Rules, and Item are the entity classes.

Domain Level Class Diagram

A Sequence Diagram

In this section, we present a typical sequence diagram for VIPANI. Figure below depicts the sequence diagram for “participate in auction” use case. Sequence diagrams for other use cases can be developed likewise

Sequence diagram for “participate in auction” use case

Figure below depicts the sequence diagram for "close auction" use case

Sequence diagram for "close auction" use case

Collaboration Diagram

Like a sequence diagram, collaboration diagrams are also used for describing interactions between various objects . Figure below depicts the collaboration diagram for the setupAuction use case. Collaboration diagrams for other use cases can be developed likewise.

Collaboration diagram for “setupAuction” use case

4. AN ARCHITECTURE FOR VIPANI

Successful systems invariably need robust, scalable and flexible architectures. In this phase the model that we have developed in the class diagrams is organized into various packages, tiers and components . The better this organization is, the more successful the system will be. The architecture of VIPANI can be described at two different levels. In the first level is the technology independent, model-driven diagram. In the second level is a technology realization of the various components of the earlier model. We refer to the first model as the Solution Model, and refer to the second model as the Technology Realization model. We use the J2EE framework to realize the Technology realization model. Adherence to a specific framework allows us to develop and integrate components faster and better.

4.1 Solution Model

Architectures of systems are known to be better in most features when they are multi-tiered. The existence of multiple tiers allows the system to be highly modular and flexible. For this reason, VIPANI is designed to be a multi-tier system. It has the following tiers:

· The Web Presentation Tier

· The Control Tier

· The Business Logic Tier

· The Data Handling Tier

· The Messaging Tier

Figure 4.1 Solution Model

The Web Presentation Tier: This tier is designed to allow the user to access the services offered by the system. The user is allowed to perform a set of well-defined operations, which achieves the ultimate business goal. Since VIPANI allows for software agents to interact with the system, it is possible for users to bypass this layer while accessing the services offered by the system. However, since the operations allowed for the agents are restricted, this layer can be considered to be the starting point of most interactions with the system.

The Control Tier: This tier essentially choreographs the various activities of the system. It is responsible for access control, right control, directing the requests to specific business logic components or data handling components, ensuring the scalability of the system by creating appropriate threads and pools of resources. This layer has the knowledge regarding the physical availability and location of the components that are below it. This layer is also responsible for load balancing.

The Business Logic Tier: This is the cardinal layer of the system. The services that are promised by the system are actually performed here. The determinations of winners and the price to be paid by the buyer to the winners, management of auctions, etc are some of the prominent functionalities of this tier. This layer may include computational resources that are distributed.

The Data Handling Tier: This tier is responsible for handling all operations related to the database(s) that store the information of the system. This tier is responsible for initializing databases, maintaining the database connections, pooling them, manipulating databases, and optimizing their performance.

The Messaging Tier: This layer is responsible for notification of various kinds of messages between the buyers and sellers. It is also used to notify any users of the system of any relevant information (like removal of users, renewal of account information, etc).

J2EE Realization Model

5. DESIGN OF VIPANI

Figure below shows the design level class diagram evolved from the analysis level class diagram. This diagram is developed by concentrating more on the Business Logic rather than the Persistence Mapping, or User Interface. The component diagram presented in the next section covers all the aspects of VIPANI.

Design Level Class Diagram for VIPANI

Design Patterns

The following design patterns were found to be apt for VIPANI:

Abstract Factory	Observer
Strategy	MVC
Factory Method	Singleton
Iterator	Mediator, Proxy

Abstract Factory

Intent: Provide an interface for creating families of related or dependent objects without specifying their concrete classes. Figure below depicts the Abstract Factory pattern where the AuctionExecutor object, depending on the auction attributes, instantiates the corresponding factory.

Participants

- AbstractFactory( FAuctionExecutor, RAuctionExecutor)

Declares an interface for operations that create concrete products.

- ConcreteFactory(FEAExecutor, FDAExecutor,FSPAExecutor,FFPAExecutor)

Implements the operations for creating the concrete products.

- AbstractProduct(FAWDM, RAWDM)

Declares an interface for a type of product object.

- ConcreteProduct(FEAWDM, FDAWDM, FFPAWDM, FSPAWDM, REAWDM,

RDAWDM, RFPAWDM,RSPAWDM)

Defines a product object to be created by the corresponding concrete factory. It also

Implements the AbstractProduct interface.

- Client

Uses only interfaces declared by AbstractFactory and AbstractProduct classes.

Strategy

Intent: Define a family of encapsulated algorithms and make them interchangeable so each algorithm can vary independently from the clients that use it.

For determining the winners and price to be paid by the winner to the auction owner, there are several algorithms for each auction mechanism. For example, a winner determination problem can be solved using an Optimization Tool Solver or some approximation algorithms such as FPTA may be applied. Thus, Strategy pattern can be used for dynamic switching between these algorithms.

The strategy pattern can be applied this way. We encapsulate the different winner determination algorithms in classes(strategy classes). Each Concrete WinnerDetermnator(eg FEAWDM so on) will define an interface which the strategy classes implement.

Same can be applied for the case of pricing unit also.

Iterator

Intent: Provide a way to access the elements of an aggregate object without exposing its underlying representation.

Figure below depicts the Iterator Pattern. Since the structure of bids under different mechanisms is different, the list of bids to be traversed also will have its own individual data structure. The Iterator pattern can be used to traverse the bid list regardless of the actual mechanism being used.

· BidListIterator defines an interface for accessing and traversing elements.

· FEA_BidListIterator, FDA_BidListIterator, FFPA_BidListIterator, FSPA_BidListIterator, and REA_BidListIterator, RDA_BidListIterator, RFPA_BidListIterator, RSPA_BidListIterator, implement the BidListIterator Interface and keep track of the current position in the traversal of the corresponding Bid List.

· BidList defines an interface for creating a BidListIterator Object.

· FEA_BidList, FDA_BidList, FFPA_BidList, FSPA_BidList, and REA_BidList, RDA_BidList, RFPA_BidList, RSPA_BidList implements the BidList interface to return an instance of the corresponding Iterator.

Observer

Intent: Define relationship amongst a collection of objects such that whenever one object is updated all its dependants are notified and updated automatically.

Here Agent object acts as Observer and Auction object acts as a Subject. During the entire auction process the agents are given information about the current highest bids value. Suppose if the auction autocloses or the auction owner wishes to stop the auction the winner determinator is called and price to be paid is determined and the auction status is notified to all the participating agents. Thus the observers are notified of the change in the subject. This is shown in Figure below.

Proxy

Intent: Provide a surrogate or place holder to control access to an object

Whenever a user uses the web-interface to avail the services offered by VIPANI, the user requests are not directly delivered to the AuctionHouse object, the main service provider.

Instead a user object is created for the user. All the web-interface requests are directed to this proxy object which in turn calls the methods of the AuctionHouse object.

Singleton

Intent: Ensure a class has only one instance and provide a global point of access

Here, if we wish to maintain our storage media distributed in the network, it is not a good idea to make multiple connections. The Singleton pattern is applied for DataManager class. DataManager is responsible for making the connection to the remote database. It provides an abstraction of where the database is located.

Also the AuctionHouse object which is the main service provider has only a single instance. Every user request will be delivered and serviced by this only object.

Factory

Intent: Define an interface for creating an object, but let subclasses decide which class to instantiate.

In VIPANI the Buying agent object can be a FEABAgent(Forward English Auction Buying Agent), FDABAgent, FFPABAgent, FSPABAgent. Based on the type of the agent the bid to submitted by the agent varies. So, here the BAgent class defines the interface for creating and submitting the bids. The classes like FEABAgent implement the methods to create the corresponding type of bids.

Product( Bid)

ConcreteProduct(FEABid,FDABid,FFPABid.FSPABid)

Creator(Bagent)

ConcreteCreator(FEABAgent, FDABAgent, FFPABAgent, FSPABAgent)

Mediator

Intent: Define an object that encapsulates how a set of objects interact.

In the Exchange Auction model all the selling agents and buying agents should have a matching between them in order to do trading. But interconnecting the agent objects directly results in tight coupling. So the XauctionExecutor object acts as a mediator for all the agent objects. Now the agents are only connected to the XauctionExecutor and it is a loosely coupled situation.

6 COMPONENT DIAGRAM FOR VIPANI

Component Diagram for VIPANI