The MAJIC system goals

The basic idea of this project is to embed an Economy mechanism into the Jini system.
This Project is based on the following basic rules/goals:

1) System/Environment:

• Create a dynamic and robust Economy environment which does not interfere with the

"old" Jini System.
• To give maximal flexibility to both Clients and Services.
• Ease of use to all users.
• Minimal Interference with the Jini Infrastructure: Conservation of all Jini mechanisms.
• Minimal effect on the performance of the system.

 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

2) Mechanism properties:

• Incentive Compatibility. Use the mechanism in such a way that Services and Clients will

be truthful regarding their evaluation price (i.e. rational "players" will be motivated to declare their
truth value).
• Maximize the profit for all users (Sellers and Buyers). The mechanism should be economy efficient

regarding the Buyers surplus, the Sellers profit and the global profit of the whole system.

The basic goals regarding the system design are as follows:

• Base most of the additional components on the Jini Infrastructure.
• Add minimum interface to this additional system.

All additional components were put in a new package (called net.jini.economy) which
is embedded inside the Jini packages. More details regarding the package.

The System behaves as follows:

1. The Service Provider (i.e. the seller) creates a well defined Contract that describes

its economic parameters.
2. When the seller join a LookUp service it submits its Contract within its attribute list.
3. The Client (i.e. the buyer) creates a Valuation class which implements the BuyerValuation

interface.
4. When the buyer searches for an appropriate service, it send its Valuation class to the LookUp

service.
5. The LookUp service (i.e. the market) finds the best seller according to the buyer Valuation class

(e.g. finds a seller that maximize the utility function of the buyer) and compute the price that
the buyer should pay to the seller upon executing the service.

Market Algorithms:
Market Algorithms (or mechanisms) can be easily added or adapted.
The Market operation is as follows:

1. Find a match (assignment) between a Buyer and a Seller according to the

desired algorithm and decide on a preferred payment.
2. Construct a Final Contract that represent the deal.
3. Send the Contract to both the Seller and the Buyer.

• utility is the utility function of the Client. Assess the Client will for buying the service.

Measured in real currency (US dollars).
• quote is the required Seller price for using this service. Also measured in US dollars.
• surplus is benefit of the Client from using the service. surplus = utility - quote.

1. Best surplus - First Price Mechanism
• Find the best Surplus for the Client. (find Seller i that maximizes the surplus of the Client).
• Assign Seller i to the Client.
• Payment <--- quote of seller i.
2. VCG like mechanism
• Find the best Surplus for the Client. (find Seller i that maximizes the surplus of the Client).
• Find the Second best Surplus for the Client. (find Seller j that maximizes the surplus of the Client without Seller i).
• Assign Seller i to the Client.
• Payment <--- (utility i - (surplus j)).  [Remark: surplus j = utility j - quote j]

 

Legal Commitments and Obligations

We shall try to describe all kind of commitments and obligations of the involved entities
(or should we say involved players).
First, the LookUp service, which acts as the market mechanism core, must be
trustable and accepted by all sides. This is the most important issue since without this basic
idea the whole model is unacceptable.

The Commitments of the Seller (the Service Provider) are:

1. Provide the service according to the SellerContract that is published inside the

LookUp service. As long as the Contract is published and Valid, the Seller must provide
the service according to the parameters published in the Contract.
2. The Seller accepts the payment for the service, that have been set by the LookUp Service

(describes in FinalContract.SellerPayement). All Mechanisms ensures that
SellerPayment >= quote(BuyerParameters)  (i.e. the Seller must earn money!)
3. The Contract is Valid as long as the Service lease is not expired and the "ProducedContractsAllowed"

field inside the SellerContract is not zeroed.
4. The Seller is required to change all necessary parameters inside its Contract whenever relevant.

It is the Seller responsibility to change the Contract and It can be done through the Jini mechanism for changing Service attributes.

1. The Buyer should execute the service during the lease duration which describes inside the

Final Contract.
2. The Buyer should pay the amount of money that was sealed inside the Final Contract (describes in FinalContract.BuyerPayment).

1. The deal between the buyer and the seller gets the final "stamp" upon the execution of the service. After the activation of the service the currency transfer can be established and the payment amounts are set according to their definition in the Final Contract.

Theoretical Analysis

We would like to examine and analyze the System on both mechanisms: Best Quote and VCG.
The overall goal is to determine the cases and scenarios which implies Incentive Compatibility from
the Seller side.
Furthermore, we would like find the assumptions, regarding the function "getParams" of the BuyerValuation,
that implies best profit to the buyer and incentive compatibility for the seller.

There are 4 sub classes (scenarios) that can be considered in a theoretical analysis:

1. Degenerate  - Both Seller Parameters and Buyer Parameters are empty.
2. Seller effect  - Seller Parameters are significant but Buyer Parameters are empty.
3. Buyer effect  - Buyer Parameters are significant but Seller Parameters are empty.
4. Complex       - Both Seller Parameters and Buyer Parameters are significant.

The net.jini.economy package

This package contains all the additional Classes/Interfaces which are necessary
to invoke the On-line market and use it correctly.
There are 3 basic classes that construct the foundation of the system:

1) SellerContract - a new attribute for JINI services. Acts as a contract that the Service is
    committed to. This abstract class contains:

• 3 necessary fields:
• Human Readable Semantics is a legal agreement that the Service is obliged to.
• contract Lease Duration defines the duration of the Sealed Contract (expiration time).
        The duration is measured in milliseconds.
• Produced Contracts Allowed The number of final contracts that the LookUp service can issued.

After issuing this number of Contracts, the Service will be erased from the LookUp service records
and would have to Join again.
• an abstract method called quote which gets the Buyer Parameters and returns the

actual price for using this service. The price measured in US Dollar ($).

2) BuyerValuation - An Interface which defines the Client valuation of a specific Service Contract.
    The Interface include two functions:

• utility function. Receives a Contract and return the utility function value of that Contract.

The utility function measured in US Dollar ($).
• getParams. Receives a SellerContract and returns the wanted BuyerParameters for that

particular Contract.

3) Buyer Parameters - A class that contains the Buyer parameters that should be visible
    to the seller. This class is constructed by the LookUp service on-line from the
    BuyerValuation instance.

Furthermore, the package contains an Interface, called EconomyServiceInterface, that a service must
implement in order to participate in this new market. The Interface allows the LookUp service to announce
the seller whenever a Final Contract is constructed and the deal is sealed.

Remark: All other Contract/Valuation Classes should extends or implements the basic Contract/Valuation.
We should notice that for every new Contract (or new contract parameters) there should
be a new (or revised) Valuation class that can evaluate it (knows how to evaluate each parameter).
Moreover, in order to create a new Contract and Valuation classes You should create a
BuyerParameters class which will contain all the parameters that can be set by the Buyer.
These Parameters should be considered inside the quote method (contract class) and should
be retrieved from the getParams method (Valuation class).
 

How to invoke an Economy LookUp service

The Invocation of an Economy LookUp Service is very similar to inocation of a
"regular" one.
Instead of the old command line:
"CreateLookup codebase policyfile dbdir [group,...] [javaprog] [javaoptions]"
there is another parameter called algorithmtype that should be set to "FirstQuote" or "SecondQuote"
according to the required Mechanism.
The new command line is:
"CreateLookup codebase policyfile dbdir algorithmtype [group,...] [javaprog] [javaoptions]"

For example: for a VCG mechanism type:
CreateLookup http://hostname:8080/reggie-dl.jar policyfile reggie_log VCG public

Instructions for Services to join the Market

Services that would like to join this On-line Market should perform the following:

• Define the Contract it would be obliged to. (Use exist Contract or create a new one)

for example: a Printer Service should use the PrinterContract.
• Construct the preferred Contract (assign values to all its members).
• Add the Contract to the attribute list that is being submitted to the LookUp service.
• Implement the EconomyServiceInterface in order to participate in the market.

Instructions for Clients to use the Market

Clients that wish to perform an "Economy lookup" should connect to LookUp Service which
contains the com.sun.jini.reggie.EconomyRegistrarProxy.
Instead of the old Interface "net.jini.core.lookup.ServiceRegistrar" the Client should use the new
Interface called "net.jini.core.lookup.EconomyServiceRegistrar", which defines a new lookup method.
The method is called lookup(ServiceTemplate,BuyerValuation).
In order to use this mechanism, the Client should create a Valuation class that implements the BuyerValuation
interface. This class can be one of the classes inside the net.jini.economy package.
 

The testing Environment

The testing environment consists of Java source files and Perl script files. The clients and services are classes written in Java. The script that invokes the services and clients with configurable parameters is written in Perl.
These files are not a part of the MAJIC system and were written only to test the system.

For the activation of the system you have to run a Web-server, Rmi deamon, and the Lookup server. Batch files that invoke all these programs exist at JINI/testing_environment. You can choose to run the system with the original JINI lookup (normal\invoke.bat), or with the MAJIC market lookup. When you run the MAJIC system, you can choose with which algorithm the lookup will work: First quote (economy\invokef.bat), Second quote (economy\invokes.bat).

Services:
The class service/GenericEconomyServer is a basic service that performs the generic actions of a service that connects to MAJIC's economy lookup. A service that wants to connect to the MAJIC system can be derived from this abstract class (for simpler coding). In the derived class the new service class can have specfic attributes and methods. The most important abstract method that the sub-class should implement is executeServiceImpl which is the method that activates the actual service for the clients.
2 services have been implemented so far:
SimpleService - a service which has only one attribute - price.
PrinterService -  a more complicated service which has few attributes such as: quality, speed, price per page, etc.

Clients:
The class service/GenericEconomyServer is a basic service that performs all the generic actions of a client that wants to get services from the MAJIC system.
A service that wants to connect to the MAJIC system should be derived from this abstract class.
2 clients have been implemented so far:
SimpleClient - a client which has a constant valuation.
PrinterClient - a client which has a number of attributes, e.g. quality_factor and number_of_pages.

Invocation script:
The services are invoked by the Perl script: JINI/testing_environment/run_test.plx (all the directories below are in the directory JINI/testing_environment).
This script reads a configuration file from the 'config' directory, with the following format:
The first line should begin with the string "lookup" (despite it is not in use - the lookup service is invoked externally).
A line that begins with "#" is a comment line.
A line the begins with the string "service" indicates that the invoker will invoke services with the parameters from this line, with the format:

service <service-name> <number_of_identical_services_to_be_invoked> <lookup_host> <host> <delay> <lease_duration> <number_of_contracts_allowed> <price> <quality_factor>

client SimpleClient <number_of_identical_clients_to_be_invoked> <lookup_host> <host> <delay_between_executions> <price>

perl run_test.plx <config_file_name> <test_number> <host_name>

We have performed the tests of the MAJIC system in the following way: the services were invoked on the NT, and the (many) clients were invoked on linux machines (inferno), and the Web-server, RMI deamon and lookup run on NT.
Invoking more than few clients on the Windows/NT can cause problems (such as memory overuse).

Jini sources Modifications

The following modifications and additions were made in the Jini system for the MAJIC system:
1. A new package was added: net.jini.economy . The package contains the basic components of the MAJIC infrastructure.
2. Classes added to net.jini.core.lookup are: EconomyServiceMatch , EconomyServiceRegistrar
3. Classes added to com.sun.jini.reggie are: EconomyRegistrar, EconomyRegistrarImpl, EconomyRegistrarProxy, DealWrapper,FinalContractLeaseImpl.
Modified classes in com.sun.jini.reggie are: CreateLookup.
The EconomyRegistrarImpl class holds the implementation of the MAJIC's economy market mechanism. The market algorithm (i.e. first quote and second quote) are implemented in it.